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Preface 



The PenPoint API Reference provides reference information on the subsystems of 
the PenPoint™ operating system. Volume I describes the functions and messages 
that you use to manipulate classes and describes the fundamental classes used by 
almost all PenPoint applications. Volume II describes the supplemental classes and 
functions that provide many different capabilities to PenPoint applications. The 
text in this volume was generated from the header files in \PENPOINT\SDK\INC. 

Intended Audience 

The PenPoint API Reference IS written for people who are developing applications 
and services for the PenPoint operating system. We assume that you are familiar 
with the C language, understand the basic concepts of object-oriented 
programming, and have read the PenPoint Application Writing Guide. 

What's Here 

The PenPoint API Reference \s divided into several parts, which are split across two 
volumes. Volume I contains these parts: 

♦ Part 1: Class Manager describes the PenPoint class manager classes, which 
supports object-oriented programming in PenPoint. 

♦ Part 2: PenPoint Application Framework describes the PenPoint Application 
Framework classes, which provides you the tools you use to allow your 
application to run under the notebook metaphor. 

♦ Part 3: Windows and Graphics describes ImagePoint classes and how 
applications can control the screen (or other output devices). 

♦ Part 4: UI Toolkit describes the PenPoint classes that implement many of the 
common features required by the PenPoint user interface. 

♦ Part 5: Input and Handwriting Translation describes the PenPoint input 
system classes and classes that provide programmatic access to the 
handwriting translation subsystems. 

Volume II contains these parts: 

♦ Part 6: Text Component describes the PenPoint classes that allow any 
application to provide text editing and formatting capabilities to its users. 

♦ Part 7: File System describes the PenPoint file system, classes. 

♦ Part 8: System Services describes the function calls that applications can use 
to access kernel functions, such as memory allocation, timer services, process 
control, and so on. 
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♦ Part 9: Utility Classes describes a wide variety of classes that save application 
writers from implementing fundamental things such as, list manipulation, 
data transfer, and so on. 

♦ Part 10: Connectivity describes the classes that applications can use to access 
remote devices. 

♦ Part 11: Resources describes the classes used to read, write, and create 
PenPoint resource files. 

♦ Part 12: Installation AP/ describes the PenPoint classes that support installing 
applications, services, fonts, dictionaries, handwriting prototypes, and so on. 

♦ Part 13: Writing PenPoint Services, describes classes used in writing an 
installable service. 

Other Sources of Information 

As mentioned above, the PenPoint Application Writing Guide provides a tutorial 
on writing PenPoint applications. The tutorial is illustrated with several sample 
applications. 

The PenPoint Development Tools describes how to run PenPoint on a PC, how to 
debug programs, and how to use a number of tools to enhance or debug your 
applications. This volume also contains a master index to the five volumes 
included in the PenPoint SDK. 

The PenPoint Architectural Reference ^rowps the PenPoint classes into several 
functional areas and describes how to use these classes. The PenPoint Architectural 
Reference is divided into two volumes. The first volume describes the fundamental 
classes that all application developers will use; the second volume describes 
supplemental classes that application developers may, or may not, use. 

To learn how to use PenPoint, you should refer to the PenPoint user documen- 
tation. The user documentation is included with the PenPoint SDK, and is usually 
packaged with a PenPoint computer. The user documentation consists of these 
books: 

♦ Getting Started with PenPoint, a primer on how to use PenPoint. 

♦ Using PenPoint, a detailed book on how to use PenPoint to perform tasks and 
procedures. 
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Type Styles in This Book 



Type Styles in Tkis Book 

To emphasize or distinguish particular words or text, we use different fonts. 

Computerese 

We use fonts to distinguish two different forms of "computerese": 

♦ C language keywords and preprocessor directives, such as switch, 
case, #def ine, #if def , and so on. 

♦ Functions, macros, class names, message names, constants, variables, 
and structures defined by PenPoint, such as msgListAddltem, clsList, 
stsBadParam, P_LIST_NEW, and so on. 

Although all these PenPoint terms use the same font, you should note that 
PenPoint has some fixed rules on the capitalization and spelling of messages, 
functions, constants, and types. By the spelling and capitalization, you can 
quickly identify the use of a PenPoint term. 

♦ Classes begin with the letters "els"; for example, clsList. 

♦ Messages begin with the letters "msg"; for example, msgNew. 

♦ Status values begin with the letters "sts"; for example, stsOK. 

♦ Functions are mixed case with an initial upper case letter and trailing 
parentheses; for example, OSMemAvailableQ. 

♦ Constants are mixed case with an initial lower case letter; for example, 
wsClipChildren. 

♦ Structures and types are all upper case (with underscores, when needed, 
to increase comprehension); for example, U32 or LIST_NEW_ONLY. 

Placeholders 

Anything you do not have to type in exactly as printed is generally formatted in 
italics. This includes C variables, suggested filenames in dialogs, and pseudocode 
in file listings. 

Other Text 

The documentation uses italics for emphasis. When a Part uses a significant term, 
it is usually emphasized the first time. If you aren't familiar with the term, you can 
look it up in the glossary in the PenPoint Application Writing Guide or: the index of 
the book. 

DOS filenames such as \\BOOT\PENPOINT\APP are in small capitals. PenPoint file 
names can be upper and lower case, such as \My DiskWPackage Design Letter. 

Book names such as PenPoint Application Writing Guide are in italics. 
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TENCODE.H 



This file contains the byte encodings used by clsText and clsTextView, 

The byte encoding employed by the Text subsystem is based on the IBM-PC code page 850. However, 
there are differences as noted by the constants below; the differences are peculiar to Text's interpretation 
of bytes, they are not part of the interpretation used by the Imaging subsystem. This byte encoding 
causes Text to use the font encoding sysDcEncodeHWX850 defined by sysfont.h. 

In addition to the constants that define the byte encoding, classifications and routines that map from a 
byte to a class are defined, similar to those classification routines provided by ctype.h. Use of these 
routines should be carefully isolated as they will be replaced by a different package in the 
"internationalized" version of PenPoint. 

The fiinctions described in this file are contained in TEXT.LIB. 



tifndef TENCODE_INCLUDED 

#define TENCODE_INCLUDED $Revision: 

tifndef GO_INCLUDED 
ttinclude <go.h> 
#endif 



1.205 $ 



Types and Constants 

"Text encoding" abbreviates to "te". 
Format effectors: recognized 



tdefine teEmbeddedObject 


0x13 


#define teSpace 


0x20 


tdefine teTab 


0x09 


tdefine teNewLine 


OxOD 


tdefine teNewPage 


OxOC 


tdefine teNewParagraph 


0x14 


tdefine teUnrecognized 


0x15 


Format effectors: unrecognized 


tdefine teBackSpace 


0x08 


tdefine teLineFeed 


OxOA 


tdefine teVerticalTab 


OxOB 



// ASCII' s DC3, 850' s ! ! 



// ASCII' s CR, 850' s music glyph 

// ASCII' s FF, 850' s female glyph 

// ASCII' sDC4, 850's para glyph 

// ASCII' s NAK, 850' s sect glyph 



The classification package is designed to support multiple classification schemes. The type 
TEXT_CHAR_TABLE represents the abstraction of a classification scheme; as such, a parameter of this 
type is required by each of the classification routines. TXTCTYPE_DEF represents the default classification 
scheme used by the Text subsystem. Thus, to see if a particular byte encodes a sentence ending character 
in the default classification scheme, the client would call: 

TEIsSentenceEnd(TXTCTYPE_DEF, aByte) 

typedef U16 TEXT_CTYPE_FLAG, *P_TEXT_CTYPE_FLAG; 
typedef P_TEXT_CTYPE_FLAG TEXT_CHAR_TABLE; 
tdefine TXTCTYPE DEF ( (TEXT CHAR TABLE) (-1L) ) 
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P" Exported Functions and Macros 



Fynction Prototype 



Commersfs 



TEIsSentenceEnd 

Determines if 'c' is a sentence-ending character. 
Returns BOOLEAN. 

BOOLEAN EXPORTED 

TEIsSentenceEnd ( 

TEXT_CHAR_TABLE table, 
CHAR c); 

Returns true if and only if 'c' is a sentence-ending character. 



Fyrsction Prototype 



Comments 



TEIsLineBreak 

Determines if 'c' forces a Une-break. 
Returns BOOLEAN. 

BOOLEAN EXPORTED 

TEIsLineBreak ( 

TEXT_CHAR_TABLE table, 
CHAR c) ; 

Returns true if and only if 'c' forces a line-break. 



Fyncfioti Prototype 



Comments 



TEIsBlank 

Determines if 'c' acts as a blank/space character. 
Returns BOOLEAN. 

BOOLEAN EXPORTED 

TEIsBlank ( 

TEXT_CHAR_TABLE table, 
CHAR c); 

More than one character may act as a blank/space for some purposes. For example, a non-breaking 
blank/space; none is defined for the PenPoint Developers Release. Returns true if and only if 'c' acts as a 
blank/space characta. 



Function Prototype 



Comments 



TEIsSpecialPunct 

Determines if 'c' is a "special" punctuation character. 
Returns BOOLEAN. 

BOOLEAN EXPORTED 

TEIsSpecialPunct ( 

TEXT_CHAR_TABLE table, 
CHAR c) ; 

Such characters end a word or sentence unless surrounded by alphanumerics. The period and commas in 
numbers are the most obvious case. Special punctuation might also include the periods in something 
like "Section II.A.i: The Rise and Fall of Punctuation". Since the surrounding context is not available to 
this function, it simply indicates whether the character can function as special punctuation; the caller 
must then examine the context to decide whether the character is actually special punctuation. 

Returns true if and only if 'c' is a "special" punctuation character. 



TENCODE.H 
Exported Functions and Macros 



TEIsWord 

Determines if 'c' is part of a "normal" word. 
Returns BOOLEAN. 

BOOLEAN EXPORTED 

Fyncfion Prototyfse TEIsWord( 

TEXT_CHAR_TABLE table, 
CHAR c); 

Comments Returns true if and only if 'c' is part of a "normal" word. 










TV TAGS.H 



This file contains clsTextView s well-known TAGs and associated constants. 
The usage of well-known TAGS by clsTextView falls into these categories: 

1) Quick Help identifiers 

2) Option Sheet card and item (i.e., window) tags 

3) Option Sheet card labels 

4) User note identifiers 

Most of clsTextView's Option Sheet components use the same tag for both the window tag and the 
quick help tag. This causes category 1 above to be almost identical to category 2. 

All of the Quick Help resources for clsTextView can be enumerated by finding all resources whose 
.wkn.admin == resForQuickHelp (see qHelp.h) and Cls(.wkn.id) == Cls (clsTextView). 



tifndef TV_TAGS_INCLUDED 
tdefine TV_TAGS_INCLUDED 

# 

tinclude <go.h> 

# 

# 

tinclude <uid.h> 

# 

// Allocated clsTextView TAGs: 1-54, 94-95 



ifndef GO_INCLUDED 

endif 

ifndef UID_INCLUDED 

endif 



Tags for Option Sheet 



typedef enum TV_CARD_INDEX { // TVMakeCardTag(TV_CARD_INDEX) => tag 

tvCardChar = 0, 

tvCardPara, 

tvCardTabs, 

tvCardView, 

tvCardLength // Pseudo-card index which gives # cards 

} TV_CARD_INDEX; 

Labels for Option sheet &: cards. All Card Label strings are in a single resource: a string array with Resid 
= tagTVOptResAdmin and indexed via TV_CARD_INDEX. 

♦define tagTVOptResAdmin MakeTag (clsTextView, 95) 

typedef enum TV_CHAR_OPTION { // TVMakeCharTag (TV_CHAR_OPTION) => tag 

tvCharOptBold = 0, 

tvCharOptFont, 

tvCharOpt Italic, 

tvCharOptSize, 

tvCharOptSizeOther, 

tvCharOptSizeOtherVal, 

tvCharOptSmallCaps, 

tvCharOpt Strike, 

tvCharOpt Style, 

tvCharOpt UnderlineNormal , 

tvCharOptUnderlineHeavy, 

tvCharOptLength // Pseudo item which gives # char options 

} TV CHAR OPTION; 
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typedef enum TV_PARA_OPTION { 
tvParaOptAfterSpacing = 0, 
tvParaOptBeforeSpacing, 
tvParaOptFirstLineOf f set , 
t vParaOpt InterLineHeight , 
tvParaOpt Justification, 
tvParaOptLeftMargin, 
tvParaOptLineHeight , 
tvParaOptRightMargin, 
tvParaOptLength 

} TV_PARA_OPTION; 

typedef enum TV_VIEW_OPTION { 
tvViewOptSpecial = 0, 
tvViewOptMagnification, 
tvViewOptLength 

} TV VIEW OPTION; 



// TVMakeParaTag (TV_PARA_OPTION) => tag 



// Pseudo item which gives # para options 



// TVMakeViewTag(TV_VIEW_OPTION) => tag 



// Pseudo item which gives # show options 



The following macros combine all of the sub-ranges into a universal name space, suitable for both 
win.tag and gwin.helpld. Note that the labels of options are not tagged, only the value fields; if the 
labels must be tagged, use a new administered range so that it does not conflict with these helplds. 



// tv_glbl.c performs runtime consistency checks. 
#define TVMakeTag (tag) 
tdefine tagTextView 
#define tagTextViewOption 
#def ine TVMakeCardTag ( i ) 
tdefine TVMakeCharOptTag(i) 
#define TVMakeParaOptTag(i) 
#define tagQHTabStop 
tdefine TVMakeViewOptTag(i) 
tdefine TVMakeXXXTag(i) 



MakeTag(clsTextView, (tag)) 
TVMakeTag (1) 
TVMakeTag (2) 
TVMakeTag (3+i) 
TVMakeTag (10+i) 
TVMakeTag ( 3 0+i) 
TVMakeTag (42) 
TVMakeTag ( 4 5+i) 
TVMakeTag (55+i) 



// min 7 => 

// min 21 => 

// min 38 => 

// min 43 => 

// min 48 => 



spare Card 
spare Char 
spare Para 
spare Tabs 
spare View 



Tags for Notes 



A Note is a string displayed to the user when a Text View encounters difficulties processing a user action. 
All of the Note strings are in a single resource: a string array with Resid = 
resForStdMsgDialog(clsTextView) and indexed via the following ids. 



tdefine tagTVNoteResAdmin 
// Allocated note ids 



MakeTag(clsTextView, 94) 
recycled: none; next: 12L 



"text view note" abbreviates to "tvn". 

tdefine tvnHazardousSetting IL 

tdefine tvnInvalidFieldValue 2L 

tdefine tvnTranslateOutOfMem 3L 

tdefine tvnTabsOverlap 4L 

tdefine tvnReadOnlyChars 5L 

tdefine tvnReadOnlyAttrs 6L 

tdefine tvnNotAnIP 7L 

tdefine tvnNotAComponent 8L 

tdefine tvnApplyWithoutSeln 9L 

tdefine tvnNegForUnsignedField lOL 

tdefine tvnNewParasAdded llL 



// margins may overlap 



//a negative number entered for an 
// unsigned field in an option sheet 






TXTDATA.H 



This file contains the API definition for clsText. 

clsText inherits firom clsObject. 

clsText is the Data Object for the Text subsystem. These objects hold characters, their attributes and 

embedded objects. 

The functions described in this file are contained in TEXT.LIB. 



Road Map 



Clients manipulating the character contents of the textData might use: 

♦ msgTextGet 

♦ msgTextGetBuffer 

♦ msgTextModify 

Clients manipulating the attributes stored in textData might use: 



msgTextChangeAttrs 
msgTextClearAttrs 
msgTextCetAttrs 
msgTextlnitAttrs 
msgTextPrintAttrs 
TextlnitCharAttrsO 
TextlnitCharMaskO 
TextlnitParaAttrsO 
TextlnitParaMaskO 
TextDeleteManyO 
TextlnsertOneO 
Clients manipulating a textData's embedded objects might use: 

♦ msgTextEmbedObject 

♦ msgTextExtractObject 

♦ msgTextEnumEmbeddedObjects 

Clients needing to work with words, sentences or paragraphs might use: 

♦ msgTextSpan 

♦ msgTextSpanType 



♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
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Clients needing to import or export text might use: 

♦ msgTextRead 

♦ msgTextWrite 

Clients observing a textData might want to handle: 

♦ msgTextAfFected 

♦ msgTextReplaced 

Characters and Encodings 

Text data objects hold bytes representing characters using the encoding specified in tencode.h. In 
PenPoint 1.0, this encoding is derived from the IBM-PCs code page 850, and uses one byte per 
character. There are characters representing line, paragraph, and page breaks. 

Characters are indexed starting from zero. 

Formatting Information 

Text data objects also hold "formatting" or "attribute" information. The types of attributes stored are: 

♦ character attributes such as font face, size and weight 

♦ paragraph attributes such margins, first line offset, first line offset 

♦ tab attributes for a paragraph 

♦ embedded object info (specifically the embedded object's uid) 

♦ link termination (specifically the destination information for marks) 

Attributes "tile" ranges of characters. In other words, no character can have two different sets of 
character attributes associated with it, although it can have both character and paragraph attributes. This 
tiling is enforced by the textData. 

Any character that does not have explicit character or paragraph attributes takes on the "default" 
character or paragraph attributes of the data object. There are messages to inspect, enumerate, and 
modify all the attributes, including the defaults. 

Relation to Ul Classes 

A textData only provides storage for characters and attributes. It does not provide any user interface 
(UI). The UI is provided by an instance of cIsTextView. 

To assist the class providing the UI, the textData provides notifications whenever either the characters or 
the attributes are modified. 

Implementation Note 

clsText is actually composed of three layers of classes. Clients need not be concerned by these layers, and 
should not rely on their existence as they may disappear in fixture releases. 

clsTextBlock (usually referred to as clsText) is a descendant of cIsTextMarkStore, which in turn is a 
descedant of clsTextChar. 

#ifndef TXTDATA_INCLUDED 

#define TXTDATA INCLUDED $Revision: 1.224 $ 
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#ifndef 

tinclude <clsmgr.h> 

#endif 

tifndef 

♦include <bytarray.h> 

tendif 

#ifndef 

tinclude <geo.h> 

#endif 

tifndef 

tinclude <sysfont.h> 

tendif 



CLSMGR INCLUDED 



BYTARRAY INCLUDED 



GEO INCLUDED 



SYSFONT INCLUDED 



// For BYTE INDEX 



// Required by sysfont.h 



// For SYSDC FONT ATTR 



Types and Constants: Atoms 

Atoms are used as parameters to many of textData messages. All valid atoms are defined below. 



typedef 


U16 ATOM; 




tdefine 


atomChar 


((ATOM) 1) 


tdefine 


atomWord 


((ATOM) 2) 


tdefine 


atomLine 


((ATOM) 3) 


tdefine 


atomSentence 


((ATOM) 4) 


tdefine 


atomPara 


((ATOM) 5) 


tdefine 


atoiiiDivision 


((ATOM) 6) 


tdefine 


atomDoc 


((ATOM) 7) 


tdefine 


atomMisc 


((ATOM) 8) 


tdefine 


atomEmbedded 


((ATOM) 9) 


tdefine 


atomParaTabs 


((ATOM) 10) 


tdefine 


atomLink 


((ATOM) 11) 


tdefine 


atomWSDelimit 


((ATOM) 12) 


tdefine 


atomClientl 


((ATOM) 28) 


tdefine 


atomClient2 


((ATOM) 29) 


tdefine 


atomClient3 


((ATOM) 30) 


tdefine 


atomClient4 


((ATOM) 31) 


tdefine 


minValidAtom 


atomChar 


tdefine 


maxValidAtom 


atomClient4 



AtomGetName 

Passes back a pointer to the string value of the atom. 

Returns STATUS. 

STATUS EXPORTED 

Fanction Prototype AtomGetName ( 

ATOM atom, 
PP_STRING ppString) ; 

Comments Most clients and subclasses do not use this fimction. It is occasionally useful for debugging. 

Return Voioe stsBadPatam atom is out of the range of valid atoms 

stsOK atom is within the valid range. *ppString may still be NULL if the atom falls into one of 
the gaps. 
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Types and Constants: Character Indices 



Character Indices 



typedef U32 

typedef TEXT_INDEX * 

tdefine maxTEXT INDEX 



TEXT_INDEX; 

P_TEXT_INDEX; 

maxU32 



Some messages and functions which take a TEXTJNDEX as a parameter may use special values to 
achieve certain effects. Each message and function description indicates which special values can be 
used. 

tdefine lpoTEXT_INDEX (maxTEXT_INDEX-inaxU16) 

tdefine lastTEXT_INDEX (lpoTEXT_INDEX-l) 

♦define infTEXT_INDEX (maxTEXT_INDEX-l) 

tdefine inInfTEXT_INDEX maxTEXT_INDEX 

"Magic" value for msgTextChangeAttrs, msgTextGetAttrs and m^TextlnitAttrs. 

#define textDefaultAttrs infTEXT INDEX 



Types and Constants: Character Attributes 

The prefixes "TA_" and "ta" indicate that an identifier is related to "text attributes." 
Use these in the alignBase field of a TA_CHAR_ATTRS. 



typedef enum { 

taNormalLineBase 
} TA_ALIGN_BASE; 

Character Attributes 



// Must fit in 2 bits 



= 0, 



typedef struct TA_CHAR_ATTRS { 



U16 



U16 



size; 



tacSpare 

highlight 

smallCaps 

uppercase 

strikeout 


8, 

1, 
1, 
1, 
1, 


underlines 


2, 


alignBase 


2; 



// Font size in twips. Not all 

// values are available — some are 

// rounded down. Max of 160*20 twips. 

// Reserved. 



// As defined in sysfont.h. Must be 

// 0, 1, or 2. 

// Use a TA_ALIGN_BASE value. Only 

// taNormalLineBase is implemented. 



SYSDC_FONT_SPEC font; 
} TA_CHAR_ATTRS, *P_TA_CHAR_ATTRS ; 

Character Attributes Mask. 

The highlight and encoding fields contain extra bits. These bits are automatically zero-ed by assigning a 
legitimate values to the field. 

// Must fit in 32 bits 

// Reserved. Should be set to 0. 

// true or false (and 1 spare bit) 



typedef struct 


{ 




U16 


tacSpare 


8, 




highlight 


2, 




size 






smallCaps 






uppercase 






strikeout 






underlines 






alignBase 




U16 


id 






group 





// mask bit for attrs.font .id 

// mask bit for attrs.font .at tr. group 
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weight 
aspect 
italic 


1, 
1, 
1, 


monospaced 
encoding 


1, 
10; 


} TA_CHAR_MASK, *P_TA_CHAR_MASK; 



// mask bit for attrs. font .attr. weight 

// mask bit for attrs. font .attr. aspect 

// mask bit for attrs. font. attr. italic 

// mask bit for attrs. font. attr. monospaced 

// mask bit for attrs. font .attr. encoding 

// true or false (and 9 spare bits) 



Types and Constants: Tab Attributes 



Each paragraph can have up to TA_MAX_TABS tab stops. A paragraph without its own explicit tab stops 
"inherits" the document's "default" tab stops. 

Paragraphs that desire uniformly spaced tab stops can compactly define the stops by setting at least two 
explicit stops and then setting repeatAtEnd to true. This has the effect of defining an unlimited number 
of implicit stops, each of which follows the prior stop by the distance between the last two explicit stops. 

NOTE: Even though each tab store has a type and leader, only the type taTabLeft and the leader 
taLeadSpace are implemented. 



typedef enum { 




// Must fit in 2 b 


taTabLeft 


= 0, 




taTabCenter 


= I, 


// Not Implemented 


taTabRight 


= 2, 


// Not Implemented 


taTabDecimal 


= 3 


// Not Implemented 


} TA_TAB_TyPE; 






typedef enum { 




// Must fit in 2 b 


taLeadSpace 


= 0, 




taLeadDot 


= 1, 


// Not Implemented 


taLeadDash 


= 2, 


// Not Implemented 


taLeadUnderline 


= 3 


// Not Implemented 


} TA_TAB LEADER; 







Tab Stop. 

The type and leader fields contain extra bits. These bits are automatically zero-ed by assigning a 
legitimate values to the field. 



typedef struct TA_TAB_STOP { 

U16 x; 

U8 type; 

U8 leader; 
} TA TAB STOP, *P TA TAB STOP; 



//In twips 

// TA_TAB_TYPE (and 6 spare bits) 

// TA TAB LEADER (and 6 spare bits) 



The maximum number of tab stops for a paragraph. 

tdefine TA_MAX_TABS 31 

Tab Stops. 

The count and repeatAtEnd fields contain extra bits. These bits are automatically zero-ed by assigning a 
legitimate values to the field. 



typedef struct TA_TABS { 
U16 count 



repeatAtEnd 
TA_TAB_STOP t abs [ 1 ] ; 
} TA TABS, *P TA TABS; 



// Number of tab stops, in the range 

// O..TA_MAX_TABS. (plus 3 

// spare bits.) 

// true or false (and 7 spare bits) 

// Actually variable size array 
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Another representation of tab stops. 

typedef struct TA_MANY_TABS { 
U16 count 



repeat AtEnd : 8; 
TA_TAB_STOP tabs [TA_MAX_TABS] ; 
} TA_MANY_TABS, *P_TA_MANY_TABS ; 

♦define textNoTabs ( (P TA MANY TABS)1) 



// Number of tab stops, in the range 

// . . TA_MAX_TABS . (plus 3 

// spare bits.) 

// true or false (and 7 spare bits) 



// Not Implemented 



Types and Constants: Paragraph Attributes 

Use these in the alignment field of a TA_PARA_ATTRS. 



typedef enum { // Must fit in 2 bits 

taParaLeft = 0, 

taParaCenter =1, 

taParaRight = 2, 

taParaSpare = 3 // Reserved 

} TA_PARA_ALIGN; 

Paragraph Attributes. 

All of the fields in TAJPARA_ATTRS that are linear measurements are in twips. 

The alignment and justify fields contain extra bits. These bits are automatically zero-ed by assigning a 
legitimate values to the field. 

IRS { 

// TA_PARA_ALIGN (and 6 spare bits) 

// or 1. (0x80 is used internally, 

// so there are 6 spare bits.) 

// The special value textUseMaxHeightOnLine 

// causes the line height to be as high 

// as the highest thing in the line. 

// Don't use zero! 

// Adds to previous paragraphs' s 
// afterSpacing 

// Add to leftMargin to get the effective 
// left margin for the first line of the 
// paragraph. 

U16 leftMargin; 

U16 rightMargin; 
} TA_PARA_ATTRS, *P_TA_PARA_ATTRS; 

Special lineHeight value 

tdefine textUseMaxHeightOnLine maxUl6 

Paragraph Attribute Mask 

The lineHeight, interLineHeight, beforeSpacing and afterSpacing fields contain extra bits. These bits 
are automatically zero-ed by assigning a legitimate values to the field. 



typedef struct 
U16 


TA_PARA_ATTRS { 
alignment : 8 
justify : 8 


U16 


lineHeight; 


U16 
U16 


interLineHeight 
beforeSpacing; 


U16 
S16 


afterSpacing; 
firstLineOffset 



typedef struct { 



// Must fit in 32 bits 



U16 


alignment 


1, 




justify 


1, 




firstLineOffset 


1, 




leftMargin 


1, 




rightMargin 


1, 




lineHeight 


3, 




interLineHeight 


8; 


U16 


beforeSpacing 


8, 




afterSpacing 


8; 


} TA PARA_ 


MASK, *P_TA_PARA_MASK; 





// or 

// or 

// or 

// or 



(2 spare bits) 
(7 spare bits) 
(7 spare bits) 
(7 spare bits) 
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Types and Constants: Embedding 



typedef struct TEXT_EMBED_OBJECT { 

TEXT_INDEX first; 

OBJECT toEmbed; 

U8 clientFlags; 

U8 action; // One of the values below (6 spare bits) 

} TEXT_EMBED_OBJECT, *P_TEXT_EMBED_OBJECT; 

Use these in the action field of a TEXT_EMBED_OBJECT. 

tdefine textEmbedCopy // For internal use only, 

tdefine textEmbedFree 1 // For internal use only, 
tdefine textEmbedlnsert 2 

tdefine textEmbedMove 3 // For internal use only. 

The fields of this structure are described in the comments for msgTextEnumEmbeddedObjects. 

typedef struct TEXT_ENUM_EMBEDDED { 

TEXT_INDEX first; 

TEXT_INDEX length; 

U16 flags; // One of the values below 

U16 max; 

U16 count; 

P_TEXT_EMBED_OBJECT pitems; 
} TEXT_ENUM_EMBEDDED, *P_TEXT_ENUM_EMBEDDED; 

The prefix "tee" indicates that an identifier is related to "TEXT_ENUM_EMBEDDED." 
Use these in the flags field of a TEXT_ENUM_EMBEDDED. 

tdefine teeFloat flagO // Include floating embedded 

// objects. (These will be 
// children of theRoot Window . ) 

tdefine teelnline flagl // Include embedded objects 

tdefine teeDefault (teeFloat | teelnline) 

Types and Constants: Import/Export 

More information about the fields of this structure is in the comments for for msgTextRead. 

The JfreeAfter and inputlsObject fields contain extra bits. These bits are automatically zero-ed by- 
assigning a legitimate values to the field. 

typedef struct TEXT_READ { 
TEXT_INDEX first; 
P_UNKNOWN input; 
U16 embeddedAction: 2, 

freeAfter: 6, // true or false (and 5 spare bits) 

inputlsObject: 8; // true or false (and 7 spare bits) 
TAG format; 

} TEXT_READ, *P_TEXT_READ; 

More information about the fields of this structure is in the comments for for msgTextWrite. 

The flags and outputlsObject fields contain extra bits. These bits are automatically zero-ed by assigning 
legitimate values to the fields. 

typedef struct TEXT_WRITE { 
TEXT_INDEX first; 
TEXT_INDEX length; 
P_UNKNOWN output; 
U16 flags; // One of the values below (and 13 



// spare bits) 



TAG format; 
U8 outputlsObject; 
} TEXT WRITE, *P TEXT WRITE; 
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The prefix "tw" indicates that an identifier is related to "text write." 

Use these in the flags field of a TEXT_WRITE. They are described in the comments for msgTextWrite. 

#define twExtractEmbedded flagO 
tdefine twTempFile flagl 
#define twForUndo flag3 

Other Types and Constants 

typedef OBJECT TEXT_DATA; 

Resource ids 

#define textResDefaultCharAttrs MakeWknResId(clsText, 1) 

tdefine textResDefaultParaAttrs MakeWknResId{clsText, 2) // Not Impl. 

tdefine textResDefaultParaTabs MakeWknResId(clsText, 3) // Not Impl. 

Public Functions and Macros 

Utility Functions 

TextDeleteMany 

Deletes characters from a textData. 
Returns STATUS. 

STATUS EXPORTED 

TextDeleteMany ( 

const OBJECT dataObj, 

const TEXT_INDEX pos, // first character to delete 

const TEXT_INDEX length) ; // number to delete 

The return values are the same as those for msgTextModify. 



Inserts one character into a textData. 


Returns STATUS. 




STATUS EXPORTED 




TextlnsertOne { 




const OBJECT 


dataObj, 


const TEXT_INDEX 


pos, 


const CHAR 


tolnsert) ; 



// position at which to insert 
// character to insert 



The return values are the same as those for msgTextModify. 



TextFindNextParaTab 

Passes back the next tab stop to the right of the passed-in stop. 

Returns STATUS. 

STATUS EXPORTED 

TextFindNextParaTab ( 

const P_TA_TABS p, 

const P_TA_TAB_STOP pTab, 

const P U16 p Index ) ; 
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Comments Note that if p->repeatAtEnd is true, there are effectively an infinite number of tab stops, 

Refyrn ¥olye stsNoMatch no tabs, ot this is the last tab. 

^ Attribute and Mask Initialization Routines 
TextlnitCharAttrs 

Initialzes a character attribute structure. 
Returns nothing. 

void EXPORTED 

Fyncfion Prototype TextlnitCharAttrs ( 

P_TA_CHAR_ATTRS p) ; 

Comments This function reads the default character attributes from the process's resource list (using the resource id 

textResDefaultCharAttrs), or sets all values to if the resource cannot be found. 

See Also msgTextChangcAttrs 



TextlnitCharMask 

Initialzes a character attribute mask to all zeros. 
Returns nothing, 
void EXPORTED 



Fyocficn Prototype TextlnitCharMask ( 

P_TA_CHAR_MASK p) ; 

See Also msgTextChangeAttrs 



TextlnitParaAttrs 

Initialzes a paragraph attribute structure to all zeros. 
Returns nothing. 



void EXPORTED 

Fo«cfioR Prototype TextlnitParaAttrs ( 

P_TA_PARA_ATTRS p) ; 

See Also msgTextChangeAttrs 



TextlnitParaMask 

Initialzes a paragraph attribute mask to all zeros. 
Returns nothing, 
void EXPORTED 



FuncfiDP Prototype TextlnitParaMask ( 

P_TA_PARA_MASK p) ; 

See Also msgTextChangeAttrs 
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Message Arguments 



The prefix "TD_" indicates tliat an identifier is related to "text data." 

The prefix "tdm" indicates that an identifier is related to "text data metrics." 



typedef struct TDJMETRICS { 

U16 flags; 

U16 spareBits; 

P_UNKNOWN spares [2]; 
} TD_METRICS, *P_TD_METRICS; 

Use these in the flags field of a TD_METRICS. 



// One of the values below 
// Reserved. 
// Reserved. 



#define tditiCanUndo flagS 
♦define tdmFileCharsOnOwn flagl 
tdefine tdmReadOnly flagO 



// if on, text Data supports undo 

// Not Implemented 

// characters cannot be modified 



expectedSize is a hint about the expected number of characters in a textData. An accurate hint can 
improve performance. 



typedef struct TD_NEW_ONLY { 

TD_METRICS metrics; 

TEXT_INDEX expectedSize; 

U16 expectedTagCount ; 
} TD_NEW_ONLY, *P_TD_NEW_ONLY; 

typedef struct TD_NEW { 

OB JECT_NEW_ONLY ob j ect ; 

TD_NEW_ONLY text; 

} TD_NEW, *P_TD_NEW; 

typedef struct TEXT BUFFER { 



// Private. For internal use only. 



TEXT INDEX first; 




// 


In 






TEXT_INDEX length; 




// 


In 






TEXT_INDEX bufLen; 




// 


In 






P_CHAR buf; 




// 


In: Out via *buf 


TEXT_INDEX bufUsed; 




// 


Out 






} TEXT_BUFFER, *P_TEXT_BUFFER; 










typedef enum { 




// 


Used 


as 


a SET 


tdForward = 1, 












tdBackward = 2 












} TEXT_DIRECTION; 












typedef struct TEXT_SPAN { 












TEXT_INDEX 


first; 






// 


In: Out 


TEXT_INDEX 


length; 






// 


In: Out 


ATOM 


type; 






// 


In: Out (for msgTextSpanTyp 


TEXT DIRECTION 


direction; 




// 


In 


BOOLEAN 


needPrefix; 




// 


In 


BOOLEAN 


needSuffix; 




// 


In 


U16 


prefixLength; 


// 


Out: valid if and only if 










// 


needPrefix is true 


U16 


suffixLength; 


// 


Out: valid if and only if 










// 


needSuffix is true 


U8 


firstNormal; 


// 


Out: or 1 (7 spare bits) 


U8 


lastNormal; 




// 


Out: or 1 (7 spare bits) 


U32 


spares [4] ; 




// 


Reserved 



} TEXT_SPAN, *P_TEXT_SPAN; 

typedef struct TEXT_SPAN_AFFECTED { 

OBJECT sender; 

U32 changeCount; 

TEXT_INDEX first; 

TEXT_INDEX length; 
} TEXT SPAN AFFECTED, *P TEXT SPAN AFFECTED; 
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typedef struct TEXT_REPLACED { 

TEXT_SPAN_AFFECTED span; 

TEXT_INDEX bytesTakenFromBuf ; 
} TEXT_REPLACED, * P_TEXT_REP LACED; 

typedef struct TEXT_AFFECTED { 

TEXT_SPAN_AFFECTED span; 

U16 remeasure; 

P_UNKNOWN spare; 

} TEXT_AFFECTED, *P_TEXT_AFFECTED; 

typedef struct TEXT_COUNTER_CHANGED { 

OBJECT sender; 

U32 changeCount; 

U32 oldCount; 
} TEXT_COUNTER_CHANGED, *P_TEXT_COUNTER_CHANGED; 
typedef struct TEXT_CHANGE_ATTRS { 

ATOM tag; 

TEXT_INDEX first; 

TEXT_INDEX length; 

P_UNKNOWN pNewMask; 

P_UNKNOWN pNewValues; 

} TEXT_CHANGE_ATTRS, *P_TEXT_CHANGE_ATTRS; 

typedef struct TEXT_GET_ATTRS { 

ATOM tag; 

TEXT_INDEX first; 

TEXT_INDEX length; // Not defined. 

P_UNKNOWN pValue s ; 

} TEXT_GET_ATTRS, *P_TEXT_GET_ATTRS ; 

Messages Defined by Other Classes 

msgNewDefaults 

Initializes the NEW struct. 

Takes P_TD_NEW, returns STATUS. Category: class message. 

ssige typedef struct TD_NEW { 

liTiertts OBJECT_NEW_ONLY object; 

TD_NEW_ONLY text; 

} TD_NEW, *P_TD_NEW; 

ttients In response to this message, clsText does the following: 

pNew->object.cap |= objCapCreate; 

memset {& (pNew->text) , 0, sizeof (pNew->text) ) ; 
pNew->text .expectedSize = 5; 

pNew->text.expectedTagCount = 5; 



msgNew 

Creates a new instance of clsText. 

Takes P_TD_NEW, returns STATUS. Category: class message. 

typedef struct TD_NEW { 

OB JECT_NEW_ONLY ob j ect ; 

TD_NEW_ONLY text; 
} TD NEW, *P TD NEW; 
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msgTextChangeCount 

Passes back (and optionally sets) the textData's changeCount. 

Takes S32, returns S32, 

tdefine msgTextChangeCount TCMakeMsg(O) 

Each instance of clsText keeps a monotonically increasing count of the number of changes that have 
been made to it (via m^TextModify). In response to this message, a textData passes back that count. 
The counter's value is always greater than or equal to 0, 

If the value of pArgs is: 

< the counter's current value is returned and the counter is unchanged. 

maxS32 the counter is incremented by one, and the new value returned. 

>= the counter is set to pArgs, and its previous value is returned. 

In general, clients should only increment the counter, not decrement it. 

msgTextGet 

Returns the character in a textData at the specified position. 

Takes TEXT_INDEX, returns STATUS. 

♦define msgTextGet TCMakeMsg(l) 

stsEndOfData pArgs->first is too large 

>= the 8 bit character is returned as the low byte of the returned STATUS; the high 3 bytes are zero. 

msgTextGetBuffer 

Passes back a contiguous range of characters from a textData. 
Takes P_TEXT_BUFFER, returns STATUS. 



#define msgTextGetBuffer 


TCMakeMsg(5) 


typedef struct TEXT_BUFFER { 




TEXT_INDEX first; 


// In 


TEXT_INDEX length; 


// In 


TEXT_INDEX bufLen; 


// In 


P CHAR buf; 


// In: Out via *buf 


TEXT_INDEX bufUsed; 


// Out 


} TEXT BUFFER, *P TEXT BUFFER; 





Use this message to get the values of several characters at a time. This message is a high-performance 
alternative to m^TextGet. 

If pArgs->length > pArgs->bufLen, then up to bufLen characters are placed into pArgs->buf 

Upon return, pArgs->bufUsed is set to the count of characters read, even if there was a problem with the 
request. 

stsBadParam pArgs->length was or pArgs->bufLen was or pArgs->buf was pNuil. 

StsEndOfData pArgs-> first is too large 

< stsOK some other error occurred. 
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msgTextGetMetrics 

Passes back the textData's metrics. 

Takes P_TD_METRICS, returns STATUS. 

#define msgTextGetMetrics TCMakeMsg{2) 

typedef struct TD_METRICS { 

U16 flags; // One of the values below 

U16 spareBits; // Reserved. 

P_UNKNOWN spares [2]; // Reserved. 

} TD METRICS, *P TD METRICS; 



insgTextLength 

Returns the number of characters stored in the textData. 

Takes nothing, returns TEXT_INDEX. 

#define msgTextLength TCMakeMsg(3) 

< stsOK some error occurred. 

>= StsOK Cast the returned value to a TEXT_INDEX; that's the number of characters. 

msgTextModify 

Modifies the characters stored in the textData. 
Takes P_TEXT_BUFFER, returns STATUS.. 



♦define msgText 


Modify 


TCMakeMsg(4) 


typedef struct 


TEXT BUFFER { 




TEXT INDEX 


first; 


// In 


TEXT INDEX 


length; 


// In 


TEXT INDEX 


bufLen; 


// In 


P CHAR 


buf; 


// In: Out via *buf 


TEXT INDEX 


bufUsed; 


// Out 


} TEXT BUFFER, 


*P TEXT BUFFER; 





Comments Use this message to insert, delete or replace characters in a textData. 

In response to this message, the textData replaces the characters in the range [pArgs->first .. 
pArgs->first+pArgs->length) with the characters from pArgs->buf. 

If pArgs->buf is pNull, the effect is a deletion. If pArgs->length is 0, the effect is an insertion. Otherwise 
the effect is a replacement. If pArgs->first is infTEXT_INDEX, the current length minus pArgs->length 
is substituted. If pArgs->length is maxTEXTJNDEX, strlen(pArgs->buf) is substituted. 

Refmn Value stsReadOniy request refused because object is read only. 

StsOK modification successful. 

msgTextSetMetrics 

Sets a textData's metrics. 

Takes P_TD_METRICS, returns STATUS. 

#define msgTextSetMetrics TCMakeMsg(6) 

typedef struct TD_METRICS { 

U16 flags; // One of the values below 

U16 spareBits; // Reserved. 

P_UNKNOWN spares [2]; //Reserved. 

} TD METRICS, *P TD METRICS; 
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msgTextSpan 

Determines the range corresponding to the requested span. 
Takes P_TEXT_SPAN, returns STATUS.. 



#ciefine msgTextSpan 


TCMakeMsgO) 


typedef i 


struct 


TEXT_SPAN { 




TEXT 


_INDEX 




first; 


text] 


_INDEX 




length; 


atom" 






type; 


TEXT_ 


DIRECTION 


direction; 


BOOLEAN 




needPrefix; 


BOOLEAN 




needSuffix; 


U16 






prefixLength; 


U16 






suffixLength; 


U8 






firstNormal; 


U8 






lastNormal; 


U32 






spares [4] ; 



// In: Out 

// In: Out 

// In: Out (for msgTextSpanType) 

// In 

// In 

// In 

// Out: valid if and only if 

// needPrefix is true 

// Out: valid if and only if 

// needSuffix is true 

// Out: or 1 (7 spare bits) 

// Out: or 1 (7 spare bits) 

// Reserved 



} TEXT SPAN, *P TEXT SPAN; 



A span is a consecutive range of characters that share some common trait. Given a position and the 
desired span type, this message returns the range of the span. For instance, a client can use this message 
to ask a textData to find the bounds of the word containing a position. 

Actually, this message can be used to find the start of one span and the end of another. If pArgs->length 
is 1, then the start and end of the same span is returned. 

If the client only needs only the beginning or the end of the span, then pArgs->direction should be set 
to the needed end. This substantially improves performance. 

Using this message, a textData can find the range of the following types of spans: 

♦ atomWSDelimit: passes back a white-space delimited span 

♦ atom Word: passes back a word span using the definitions in tencode.h 

pArgs->type specifies the desired span's type. 

pArgs->direction indicates whether the span should be searched for in preceding characters, succeeding 
characters, or both. 

It is often useful to know something about the characters immediately preceding or succeeding the span. 
This information is returned if pArgs->needPrefix or pArgs->needSuffix (or both) are true. Upon return, 
pArgs->prefixLength and/or pArgs->suffixLength identifies the appropriate characters. 

pArgs->firstNormal and pArgs->lastNormal indicate whether the corresponding portions of the span are 
normal or abnormal characters for the span. For instance, for atomWord, an "a" is a normal character, 
but an "!" is abnormal. 



stsBadParam Neither the two directions in pArgs->direction was on. 
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Messoge 
Arguments 



Comments 



msgTextSpanType 

Determines the span type of the specified range. 
Takes P_TEXT_SPAN, returns STATUS.. 
tdefine msgTextSpanType TCMakeMsg(lO) 

// In: Out 
// In: Out 

// In:Out (for msgTextSpanType) 
// In 
// In 
// In 

// Out: valid if and only if 
// needPrefix is true 
// Out: valid if and only if 
// needSuffix is true 
// Out: or 1 (7 spare bits) 
// Out: or 1 (7 spare bits) 
// Reserved 
} TEXT_SPAN, *P_TEXT_SPM; 

In response to this message, a textData passes back the span type that corresponds to the range. 

The same range often has several span types. For instance, all ranges have the span type atomChar. All 
ranges that include a complete paragraph also have the span types atomChar, atomWord and 
atomSentence. When the passed-in range has multiple span types, the largest span type is returned. 

The span type ordering from smallest to largest is as follows. This is also the complete list of span types 
returned in response to this message. 

♦ atomChar 

♦ atomWord 

♦ atomSentence 

♦ atomPara 

♦ atomDoc 



typedef struct 


TEXT_SPAN { 




TEXT_ 


_INDEX 




first; 


text] 


JNDEX 




length; 


atom' 






type; 


TEXT 


DIRECTION 


direction; 


BOOLEAN 




needPrefix; 


BOOLEAN 




needSuffix; 


U16 






prefixLength; 


U16 






suffixLength; 


U8 






firstNormal; 


U8 






lastNormal; 


U32 






spares [4] ; 



message 
krguments 



m^TextChangeAttrs 

Changes the attributes of the specified range. 
Takes P_TEXT_CHANGE_ATTRS, returns STATUS. 



Commeofs 



♦define msgTextChangeAttrs 



TAMakeMsg(taVersion, 1) 



typedef struct TEXT_CHANGE_ATTRS { 

ATOM tag; 

TEXT_INDEX first; 

TEXT_INDEX length; 

P_UNKNOWN pNewMask; 

P_UNKNOWN pNewValues; 

} TEXT_CHANGE_ATTRS, *P_TEXT_CHANGE_ATTRS ; 

Clients use this message to change the formatting attributes of characters in a textData. They can 
manipulate three types of attributes: 

♦ character attributes (indicated by atomChar) 

♦ paragraph attributes (indicated by atomPara) 
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♦ tab attributes (indicated by atomParaTabs) 

The pArgs type for this message is P_TEXT_CHANGE_ATTRS. This structure has a tag, which must be 
one of the three atoms mentioned above. The structure also has two P_UNKNOWN fields: pNewMask 
and pNewValues. The true type of these two fields depends on the value of the tag. 

tag pNewValues type pNewMask type 



atomChar P_TA_CHAR_ATTRS P_TA_CHAR_MASK 

atomPara P_TA_PARA_ATTRS P_TA_PARA_MASK 

atomParaTabs P_TA_MANY_TABS none; always null 

The mask field allows the client to change only some of the attributes. If the appropriate bit in the mask 
if off, then the value of the attribute is not changed. To simplify initializing attribute and mask 
structures, textData has a few utility messages and functions: 

msgTextlnitAttrs The client must set the tag pArgs->first. In response to this message, a textData 
initializes pNewValues to the values in effect at pArgs->first and sets all of the bits in the mask to 
zero. 

TextlnitCharAttrs reads the default character attributes from the process's resource list (using the 
resource id textResDefaultCharAttrs), or sets all values to if the resource cannot be found. 

TextlnitCharMask Turns off all bits in the mask 

TextlnitParaAttrs Sets all values to 0. 

TextlnitParaMask Turns off all bits in the mask 

If pArgs->first is the "magic value" textDefaultAttrs, the textData's default attributes are modified. 

If pArgs->tag is atomPara or atomParaTabs, then the passed-in range is automatically extended to 
complete paragraph boundaries. (The resulting range is passed back in pArgs->first and pArgs->length 
updated.) 

storrs ¥ai«e stsBadParam Either pArgs->tag or the range was invalid. No attributes have changed. 

< stsOK Some other error occurred. No attributes have changed. 



msgTextClearAttrs 

Clears all attributes of the specified type to the default values. 

Takes ATOM, returns STATUS. 

#define msgTextClearAttrs TBMakeMsg(5) 

>mr«eiits In response to this message, a textData clears all formatting for the specified type. This message is "all or 

nothing" ~ no mask or range can be specified. 

The attributes have not changed the return value is < stsOK: 

■$tum Voioe stsBadParam pArgs was invalid. No attributes have changed. 

< StsOK Some other error occurred. No attributes have changed. 



nisgTextEmbedObject 

Embeds an object at a specified position. 

Takes P_TEXT_EMBED_OBJECT, returns STATUS. 

♦define msgTextEmbedObject TBMakeMsg(2) 
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Message typedef Struct TEXT_EMBED_OBJECT { 

krqumenfs TEXT_INDEX first; 

OBJECT toEinbed; 

U8 clientFlags; 

U8 action; // One of the values below (6 spare bits) 

} TEXT_EMBED_OBJECT, *P_TEXT_EMBED_OB JECT ; 

'.omments Each embedded object is represented by a character with the encoding value teEmbeddedObject. (See 

tencode.h.) 

In response to this message, the textData inserts the embedded object anchor character and 
"remembers" the embedded object's id. 



I«€SSC 



msgTextExtractObject 

Extracts the specified embedded object. 

Takes OBJECT, returns STATUS. 

tdefine msgTextExtractObject TBMakeMsg(4) 

In response to this message, the textData "forgets" the specified embedded object. It also deletes the 
associated embedded object anchor character. 

Nothing is done to the object itself In particular, the client should probably msgWinExtract the object. 



msgTextGetAttrs 

Gets the attributes of the specified type. 

Takes P_TEXT_GET_ATTRS, returns STATUS. 

tdefine msgTextGetAttrs TAMakeMsg(taVersion, 2) 



typedef struct TEXT_GET_ATTRS { 
Arguments ATOM tag; 

TEXT_INDEX first; 

TEXT_INDEX length; // Not defined. 

P_UNKNOWN pValues; 

} TEXT_GET_ATTRS, *P_TEXT_GET_ATTRS ; 

Corrtmersts Clients Can retrieve the attributes of a character in the textData using msgTextGetAttrs. 

The client specifies the type of attributes it is interested in by filling in pArgs->tag. The client must set 
pArgs->pValues to point to a structure vvrith the "real" type of the attributes corresponding to the t^. 
This "real" type is described in the comments for m^TextChangeAttrs. 

The client also specifies the character whose attributes the client wants by specifying pArgs->first. If 
pArgs->first is textDefaultAttrs then the default attribute values are returned. 

tefyrn ¥cii«e stsBadParam pArgs->tag is not valid 

stsEndOfData pArgs->first is too large 

stsOK the attribute values have been copied into pArgs->pValues 

msgTextlnitAttrs 

Initialize the attributes and mask before a msgTextChangeAttrs. 

Takes P_TEXT_CHANGE_ATTRS, returns STATUS. 

tdefine msgTextlnitAttrs TAMakeMsg (taVersion 3) 
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Message typedef Struct TEXT_CHANGE_ATTRS { 

irgiiments ATOM tag; 

TEXT_INDEX first; 

TEXT_INDEX length; 

P_UNKNOWN pNewMask; 

P_UNKNOWN pNewValue s ; 

} TEXT_CHANGE_ATTRS, *P_TEXT_CHANGE_ATTRS; 

:omi»enfs The type of attributes is specified by pArgs->tag. pArgs->pNewValues and pArgs->pNewMask must be 

set as appropriate to an invocation of m^TextChangeAttrs. 

If pArgs->first is textDefaultAttrs, the default attributes are used to initialize pArgs->pNewValues. 
Otherwise the attributes in effect at pArgs->first are used. All bits of pArgs->pNewMask are set to 0. 

tetorsi ¥aiye stsBadParam Either pArgs->tag or the range was invalid. 

< stsOK Some other error occurred. No change has been made to the attributes and mask. 

fee Also msgTextChangeAttrs 

msgTextPrintAttrs 

Prints the values of an attribute set and a mask. 
Takes P_TEXT_CHANGE_ATTRS, returns stsOK. 

tifdef DEBUG 

tdefine msgTextPrintAttrs TAMakeMsg(taVersion, 4) 

tendif 

tessoge typedef struct TEXT_CHANGE_ATTRS { 

Irgoments ATOM tag; 

TEXT_INDEX first; 

TEXT_INDEX length; 

P_UNKNOWN pNewMask; 

P_UNKNOWN pNewValues; 

} TEXT_CHANGE_ATTRS, *P_TEXT_CHANGE_ATTRS ; 

ZommBnts This message takes the same parameters as msgTextChangeAttrs and the pArgs must be filled in the 

same way. In response to this message, a textData prints out a useful dump of the contents of pArgs. 

Internal Use Only: If pArgs-> first is txtPrvAttrs, then pArgs->pNewValues must be in the internal 
format. 

lee Aiso msgTextChangeAttrs 



msgTextRead 

Inserts Ascii, RTF, etc. at the specified location. 

Takes P_TEXT_READ, returns STATUS. 

tdefine msgTextRead TBMakeMsg(O) 

Messoge typedef struct TEXT_READ { 

Arguments TEXT_INDEX first; 

P_UNKNOWN input; 
U16 embeddedAction: 2, 

freeAfter: 6, // true or false (and 5 spare bits) 

inputlsObject: 8; // true or false (and 7 spare bits) 
TAG format ; 

} TEXT_READ, *P_TEXT_READ ; 

CoRiiiieiits The textData reads data and inserts the data into itself 
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The fields of pArgs are: 

first the read text is inserted into the textData starting at this position. After a successful return, 
pArgs->first is position immediately afi:er the inserted text. 

input the input source. If pArgs->inputIsObject is true, this field must hold a FILE_HANDLE object. If 
pArgs->inputIsObject is false, then this field must hold a P_FILE. 

embeddedAction Client must set this to textEmbedlnsert. (Other values are for internal use only.) 

freeAfter If true, then pArgs->input is freed after reading successfully. 

inputlsObject describes the type of pArgs->input. 

format one of the file types defined in filetype.h, or fileTypeUndefiined. If the latter, the textData 
object attempts to deduce the form at from the contents of the data found in pArgs->input. 

The textData reads pArgs->input using the functions defined in stdio.h. Thus, if pArgs->inputIsObject 
is true, pArgs->input must be an object which supports the stream protocol as used by stdio. 

teturn Voiwe stsReadOnly request refused because object is read only. 

stsNoMatch RTF error: first character of input is not "{" or format version > 1 or unrecognized font 
name. 

stsFailed StdioStreamBindQ or fseek() failed. 

stsBadParam pArgs->format is invalid. 

stsFS... see <fs.h>. 

stsOK request completed successfiilly; pArgs->first updated. 



msgTextWrite 

Outputs the specified span as one of Ascii, RTF, etc. 

Takes P_TEXT_WRITE, returns STATUS. 

♦define msgTextWrite TBMakeMsg(l) 

^ss«ge typedef struct TEXT_WRITE { 

eymenfs TEXT_INDEX first; 

TEXT_INDEX length; 

P_UNKNOWN output; 

U16 flags; // One of the values below (and 13 



// spare bits) 



TAG format ; 
U8 output I sObject; 
} TEXT WRITE, *P TEXT WRITE; 



The fields of pArgs are: 

first first character of range to be written 

length length of range to be written 

output if null, the textData creates a P_FILE and returns that handle. If non-null, then this field is 
either an object or a P_FILE, depending on the value of outputlsObject. 

flags described below 

format one of the file types defined in filetype.h. 

outputlsObject If output is non-null and outputlsObject is true, then output is an object. If output is 
non-null and outputlsObject is false, then output is a P_FILE. 



28 PENPOINT API REFERENCE 

Part 6 / Text 

Possible values for the flags field of a TEXT_WRITE are: 

twExtractEmbedded embedded objects in the specified span are extracted from their parent window, 

twTempFile if output is null, then a temporary file is created. (Developer's Note: If you're debugging 
the behavior of msgTextWrite, you probably don't want to turn this flag on as your file will be 
deleted before msgTextWrite returns.) 

twForUndo add additional information needed for supporting UNDO. 

storn ¥oii?e stsBadParam pArgs->format is invalid. 

stsFailed StdioStreamBind() failed. 

stsFS... see <fs.h>. 

stsOK request completed successfiilly. 



msgTextEnumEmbeddedObjects 

Enumerates the textData's embedded objects. 

Takes P_TEXT_ENUM_EMBEDDED, returns STATUS. 

tdefine msgTextEnumEmbeddedObjects TMMakeMsg(9) 

typedef struct TEXT_ENUM_EMBEDDED { 

TEXT_INDEX first; 

TEXT_INDEX length; 

U16 flags; // One ofthe values below 

U16 max; 

Ul 6 count ; 

P_TEXT_EMBED_OBJECT pitems; 
} TEXT_ENUM_EMBEDDED, *P_TEXT_ENUM_EMBEDDED; 

There are two ways of enumerating the embedded objects: 

1) Get all the objects in one send. The textData allocates an array of TEXT_EMBED_OBJECT elements 
and passes it back in pArgs->pItems. You must OSHeapBlockFreeQ the array when you are done with it. 
TEXT_ENUM_EMBEDDED is used as follows: 

first position at which you want to start the enumeration. Use to start at the beginning ofthe data. 

length length ofthe range you want the enumeration to include. Use infrEXT_INDEX to go to the 
end ofthe data. 

flags Usually teeDefault. Use teeFloat to get only floating embedded objects. Use teelnline to get only 
in-line embedded objects. 

max Pass in 0. The object passes back the number of items in the allocated block 

count Pass in maxU16. The object passes back the number of items returned (same as max). 

pitems Pass in pNull. The object passes back a pointer to the allocated block 

2) Get the objects a few at a time. You repeatedly send msgTextEnumEmbeddedObjects re-using the 
same TEXT_ENUM_EMBEDDED structure. When the message returns stsEndOfData, there are no more 
objects in the enumeration. You should set the fields of TEXT_ENUM_EMBEDDED only before the first 
call. For successive calls you must not modify the fields. 

first Same as Case 1 . 

length Same as Case 1 . 

flags Same as Case 1 . 
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max number of objects the pitems block can hold. 

count Pass in the same value as max. textData passes back the number of objects returned in block. 
May be less than max for the last chunk, and is when no further objects are left to enumerate. 

pitems pointer to a block that can hold at least max objects. 

stsOK next chunk of objects has been enumerated 

stsEndOfData no more objects to enumerate. Passed back count is be zero. If pitems was nil and max 
was 0, then no block has been allocated. 



Notifications 



msgTextAffected 

Notifies observers that a range of text has been affected. 

Takes P_TEXT_AFFECTED, returns STATUS.. 

#define msgTextAffected MsgNoError(TCMakeMsg{7) ) 

typedef struct TEXT_AFFECTED { 

TEXT_SPAN_AFFECTED span; 

U16 remeasure; 

P_UNKNOWN spare; 

} TEXT_AFFECTED, *P_TEXT_AFFECTED; 

This message informs observers that the attributes of the range have been modified. 



msgTextCounterChanged 

Notifies observers that textData s changeCount has been modified. 

Takes P_TEXT_COUNTER_CHANGED, returns STATUS.. 

#define msgTextCounterChanged MsgNoError (TCMakeMsg(ll) ) 

Viesscsge typedef struct TEXT_COUNTER_CHMGED { 

irfiimeiits OBJECT sender; 

tJ32 changeCount ; 

U32 oldCount; 
} TEXT_COUNTER_CHANGED, *P_TEXT_COUNTER_CHANGED ; 

z&mmmits The changeCount is normally incremented by 1 as a result of handling msgTextModify. Observers here 

about these changes via m^TextRepIaced and m^TextAffected notification messages. 

However, the changeCount can change in other ways. For instance, the changeCount is rolled back as 
part of undoing certain operations. Also, clients and/or subclasses can explicitly set the changeCount via 
magTextChangeCount. 

Whenever the changeComit changes in some way OTHER than a single increment by 1, 
msgTextCounterChanged is sent to the observers to allow them to synchronize any caches they keep 
based on the changeCount. 



msgTextReplaced 

Notifies observers that a range of text was replaced via m^TextModify. 

Takes P_TEXT_REPLACED, returns STATUS.. 

tdefine msgTextReplaced MsgNoError (TCMakeMsg (8) ) 
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typedef struct TEXT_REPLACED { 

TEXT_SPAN_AFFECTED span; 

TEXT_INDEX bytesTakenFroiiiBuf ; 
} TEXT REPLACED, *P TEXT REPLACED; 
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TXTVIEW.H 



This file contains the API definition for clsTextView and clsTextlP. 

clsTextView inherits from clsView. 

clsTextView implements the user interface of a text editor. It uses an instance of clsText (or one of its 
subclasses) to hold its data. 

clsTextlP inherits from clsIP. 

clsTextlP is a specialization of clsIP used by a Text Views. 

The functions described in this file are contained in TEXT.LIB. 



Introduction 



An instance of clsTextView (or textView) provides a user interface which presents text data to the user 
and lets the user edit that data. 

Every textView has an associated data object of clsText (or a subclass of clsText). This object is referred 
to as textData. 



Painting Model 

A textView displays the textData as a series of non-overlapping, exhaustively tiling, horizontal display 
lines. With the possible exception of space below the last line, there is no area between lines that does 
not belong to any line. Characters are laid out left to right with lines running from top to bottom. 

When first created, the textView positions the first line of textData at the top of itself. Subsequent user 
or client actions (e.g. scrolling) can position some other line to the top of the window. However, the top 
line is always completely visible unless the view is too small to allow this. The last visible line, in 
contrast, may be clipped at the bottom. 

Even though a textView is a descendant subclass of clsBorder, clsTextView ignores all clsBorder 
fiinctionality relating to display of the view's background and border. 

Deferred Repaint 

A textView uses a "delayed repair" model in which several changes to the textData may be made before 
the visible display lines are repainted. For certain operations (e.g. selection change), such a delay can be 
misleading to the user and the individual operations provide a way to override the normal delay. If no 
override is available within a message's arguments, msgTextViewRepair can be used. 

Word Wrap 

By default, a textView displays each line beginning at the left edge of its window and "word wraps" at 
the right edge. That is, if a word would be clipped by the right edge of the window, it is instead placed at 
the beginning of the next line. By modifying paragraph margin attributes the line can be adjusted to 
have uninked margins in which no character is displayed. 



32 PENPOINT API REFERENCE 

Part 6 / Text 

Word wrap can be turned ofFby setting the textView's style (see m^TextViewSetStyie). When off, a line 
breaks only when a "hard break" character (such as teNewLine or teNewParagraph) is encountered. As a 
result, a significant portion of many lines may be invisible to the user. 

Embedded Objects 

Other objects can be embedded within a textView (see msgTextViewAddlP and m^TextViewEmbed). 
(All embedded instances of some subclasses of clsEmbeddedWin.) 

A textView handles an embedded object as if it is a "very large" character. 

The textView's displayed lines are always as tall as the tallest character or embedded object in the line. 
Therefore the presence of a large embedded object causes the containing line to be quite tall, (Not all 
embedded objects are large. For instance, closed application icons and reference buttons are only slightly 
larger than typical text.) 

The baseline of the line containing embedded objects is determined, in part, by the embedded object's 
response to msgWinGetBaseline. (See win.h.) 

Text IPs 

An instance of clsTextlP (or textIP) implements two special features that are useful to textViews. 

The first is size management. An embedded textIP tracks the width of its parent window. When the 
parent's width changes, an embedded textIP modifies its own width so that it fits within and completely 
fills the parent window (in the horizontal direction). 

The second is special filtering of text going from the IP into a textView. A textIP filters translated data 
from its superclass (clsIP) before passing its data onto its client (typically a textView). Two kinds of 
filtering are performed: paragraph break insertion and space correction. A textIP inserts paragraph 
breaks based on how many blank lines there are between scribbles on an IP. textIP also filters out 
unnecessary spaces between words and adds spaces after a sentence-ending character such as a period or 
question-mark. 

Limitations 

textView is not WYSIWYG: although it will closely match font sizes and line breaks and spacing on a 
printer, it is based on a "make the printer match the screen" model that has enough variability that 
clients requiring WYSIWYG will find unacceptable (e.g., an overlaying mark-up layer). 

textViews do not support multiple views of a single data object. Thus each textView is the unique view 
for its textData object. This restriction is not checked by clsTextView. 

Although TV_NEW_ONLY has a "dc" field, there are so many restrictions on its use in PenPoint 1.0 that 
the field should always be left at the default value of Nil (OBJECT). In addition, changing the units or 
scale used by the view-allocated "dc" is forbidden. This prevents "magnifying glass" and "pan in or out" 
effects from being used with a textView. 

tifndef TXTVIEW_INCLUDED 

tdefine TXTVIEW_INCLUDED $Revision: 1.214 $ 

tifndef TXTDATA_INCLUDED 

# include <txtData.h> // For TEXT_INDEX 

#endif 
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Types and Constants 

typedef OBJECT TEXT_VIEW; 

Message Arguments 

Text Vievy Style 

The prefix "TV" indicates that an identifier is related to 'TextView." 
The prefix "tvs" indicates that an identifier is related to "text view style." 



typedef struct TV_STYLE { 
U16 flags; 
S8 magnification; 



U8 



showSpecial; 



OBJECT printer; 
} TV STYLE, *P TV STYLE; 



// One of the values below 

// when tvsFormatForPrint is not on, this 

// value (in points) is added to the 

// character font sizes. 

// 0: show no special characters. 

// 1: undefined — do not use. 

// 2: undefined — do not use. 

// 3: show all special characters. 

// (6 spare bits) 

// Not implemented. Should be null. 



Use these flags in the flags field of TV_STYLE: 

tvsEmbedOnlyComponents can only embed components. Cannot embed apps 

tvsEmbedOnlylPs can only embed subclasses of clsIP. Can embed no other objects. 

tvsFormatForPrinter printer preview, style.magnification is ignored. 

tvsQuietWarning don't display warning notes to user 

tvsQuietError don't display error notes to user 

tvsQuiet both tvsQuietWarning and tvsQuietError 

tvsReadOnlyChars characters are read-only; user cannot add, remove or replace characters. 

tvsReadOnlyAttrs attributes are read-only; user cannot change any attribute information, 

tvsReadOnly both tvsReadOnlyChars and tvsReadOnlyAttrs 

tvsWordWrap break display line by wrapping words that don't fit at the right edge of the view. 

tdefine tvsEmbedOnlyComponents flagO 



#define tvsEmbedOnlylPs 
♦define tvsFormatForPrinter 
#define tvsQuietWarning 
#define tvsQuietError 
tdefine tvsQuiet 
tdefine tvsReadOnlyChars 
#define tvsReadOnlyAttrs 
tdefine tvsReadOnly 
tdefine tvsWordWrap 
fdefine tvsSparel 
tdefine tvsSpare2 
tdefine tvsSpareS 
tdefine tvsSpare4 
tdefine tvsSpareS 



(tvsEmbedOnlyComponents | f lagl) 

flag2 

flags 

flag4 

(tvsQuietWarning | tvsQuietError) 

flags 

flag6 

(tvsReadOnlyChars | tvsReadOnlyAttrs) 

flagV 

flags // Reserved 

flag9 // Reserved 

(flagl0|flagll|flagl2|flagl3) // Reserved 

flagl4 // Reserved 

flaglS // Reserved 
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Embedding 

TV_EMBED_METRICS describes where and how to embed an object. The cUent either specifies the object 
to embed, or sets the embedded field to Nil and lets the text view create a new object based on the flags 
field. In the latter case, the UID of the newly created object is passed back in the embedded field. 

typedef struct TV_EMBED_METRICS { 

TEXT_INDEX pos; // In: embedded object is inserted 

// just before this position. 
U16 flags; // One of the values below 

OBJECT embedded; // In-Out: the UID of the embedded object 

} TV_EMBED_METRICS, *P_TV_EMBED_METRICS; 

Use these in the flags field of a TV_EMBED_METRICS. 

♦define tvEmbedAnnotate flagO // Not implemented 

#define tvEmbedFloat flagl // Make the embeddee floating 

♦define tvEmbedReplace flag2 // The IP's contents replace the 

// character following the IP. 

Use this in the flags field of a TV_EMBED_METRICS. 

♦define tvEmbedAddMargin flagS // Leave small between previous line 

// and the IP. 

Use these in the flags field of a TV_EMBED_METRICS when using the struct as the pArgs to 
msgTextViewAddlP. 

♦define tvEmbedAtEnd flagS // IP should be last char of data. 

♦define tvEmbedPara flag9 // IP is a paragraph pad 

♦define tvEmbedOneChar flaglO // IP is only 1-char 

♦define tvEmbedP reload flagll // preload the selection into the IP 

♦define tvEmbedDisplayType (flagl3|flagl4|flagl5) // Obsolete. 

Resolution 

The prefix "tvr" indicates that an identifier is related to "text view resolve." 

The values for the xRegion and yRegion fields of a TV_RESOLVE struct are illustrated here. The values 
are of the form (xRegion, yRegion). 

I I 

(-1,1) I (0,1) I (1,1) 

I I 

I I 

I Line's ink | 
(-1,0) I (0,0) I (1,0) 

I I 

I I 

(-1,-1) I (0,-1) I (1,-1) 

I I 



XY32 


xy; 


U16 


flags; 


TEXT_INDEX 


pos; 


TEXT_INDEX 


lineStart; 


S8 


xRegion; 


S8 


yRegion; 


TEXT INDEX 


selects; 


XY32 


offset; 


P UNKNOWN 


spares [4] ; 


TV RESOLVE, *P 


_TV_RESOLVE; 
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The fields of this structure are described in more detail in the comments for msgTextViewResolveXY. 

typedef struct TV_RESOLVE { 

// In: Out: Units are LWC 

// One of the values below 

// Out: Pos of char containing xy, or 

// maxTEXT_INDEX if no such char 

// Out: Pos of first char on line 

// containing xy, or maxTEXT_INDEX 

// if no line contains xy. 

// Out: Region x was in. See diagram. 

// Out: Region y was in. See diagram. 

// Out: Pos of char "selected" by xy 

// Out: Offset to prev/next char's ink 

// Reserved. 

Use these flags in the flags field of TV_RESOLVE. Note that they are not completely orthogonal; in 
particular, only one of [tvrSelFirst, tYrSelLPO and tvrBalance] should be enabled at once, similarly for 
[tvrPrevChar and tvrNextChar] . 

tvrSelFirst causes TV_RESOLVE.selects to be <= TV_RESOLVE.pos (i.e., the "selected" character is at or 
before the character "hit" by TV_RESOLVE.xy.) 

tvrSelLPO causes TV_RESOLVE.selects to be >= TV_RESOLVE.pos (i.e., the "selected" character is aft:er 
the character "hit" by TV_RESOLVE.xy, unless the line contains only one character in which case 
TV_RESOLVE.selects == TV_RESOLVE.pos,) 

tvrBalance has the effect of tvrSelFirst or tvrSelLPO, depending on v^hich edge of the character "hit" 
by TV_RESOLVE.xy is closest to TV_RESOLVE.3y.x. 

tvrSelWord causes the "selection" behavior specified by any of the previous three flags to occur for the 
"word" containing the character "hit" by TV_RESOLVE.xy.x. 

tvrPrevChar normally TV_RESOLVE.offset.x is upon return. Enabling tvrPrevChar causes 

TV_RESOLVE.ofifset.x to contain the amount that TV_RESOLVE.xy.x exceeds the x coordinate of the 
lower-left corner of the character specified by TV_RESOLVE.pos (i.e., the distance past the previous 
character's right edge). 

tvrNextChar normally TV_RESOLVE.offset.x is upon return. Enabling tvrNextChar causes 

TV_RESOLVE.ofFset.x to contain the amount that TV_RESOLVE.xy.x falls short of the x coordinate of 
the lower-right corner of the character specified by TV_RESOLVE.pos (i.e., the distance before the 
next character's lefi: edge). 

tvrPastEOL normally a line contains only those character positions for the characters displayed on the 
line. tvrPastEOL permits TV_RESOLVE.selects to return with the TEXT_INDEX of the first character 
of the following line if the specified TV_RESOLVE.:!9^.x is to the right of the last character in the Une. 

tvrNLIfPastEOL when disabled, if TV_RESOLVE.59^.x is to the right of the last character in a line with a 
hard line break (e.g., teNewLine or teNewParagraph) and at least one other character, 
TV_RESOLVE.selects specifies the character immediately before the hard line break. When enabled, if 
tvrPastEOL is also enabled and would have caused TV_RESOLVE.selects to be afi;er the hard line 
break, tvrNLIfPastEOL will override and cause TV_RESOLVE.selects to specify the break character 
instead. 

tdefine tvrSelFirst flagO 

tdefine tvrSelLPO flagl 

tdefine tvrSelWord flag5 

tdefine tvrPrevChar flag2 

tdefine tvrNextChar flag3 

tdefine tvrBalance flag4 

tdefine tvrPastEOL flag6 
tdefine tvrNLIfPastEOL flag7 
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Selection 

The prefix "tvs" indicates that an identifier is related to "text view select." 

The fields of this structure are described in more detail in the comments for msgTextViewSetSelection. 

typedef struct TV_SELECT { 

TEXT_INDEX first; // lpoTEXT_INDEX means "clear selection" 

TEXT_INDEX length; // results in an length selection 

U16 flags; // either or wsSynchRepaint (see win.h) 

ATOM level; // Obsolete. Don't use. 

} TV_SELECT, *P_TV_SELECT; 

Scrolling 

The prefix "ts" indicates that an identifier is related to "text view scroll." 

typedef struct TV_SCROLL { 

TEXT_INDEX pos; // Position to scroll to 

U32 flags; // One of the values below 

} TV_SCROLL, *P_TV_SCROLL; 

Use these in the flags field of a TV_SCROLL. 

tsAlignAtTop scroll so that pArgs->pos is "near the top." See tsAlignEdge. 

tsAlignAtBottom scroll so that pArgs->pos is "near the bottom." See tsAlignEdge. 

tsAlignAtCenter scroll so that pArgs->pos is in the center displayed line 

tsAlignEdge If set, and tsAlignAtTop or tsAlignAtBottom is set, this flag forces the line containing 
pArgs->pos to be the exact edge. If this flag is off, and tsAlignAtTop tsAlignAtBottom is set, the 
textView tries to leave an extra line or two between the line containing pArgs->pos and the view's 
edge. 

tsIfHnvisible If set, the textView scrolls only if pArgs->pos is not already visible. If not set, the 
textView scrolls even if pArgs->pos is visible. 

textNoScrollNotify By default, the scrollbar(s) for the view are notified (via a msgWinSend of 
msgScrolibarUpdate) that they should update afi:er a m^TextViewScroU. If this flag is set, the 
notification is not sent. 

♦define tsAlignAtTop OL 

tdefine tsAlignAtBottom IL 

tdefine tsAlignAtCenter 2L 

♦define tsAlignEdge ((U32)flag2) 

♦define tslff Invisible ((U32)flag3) 

♦define textNoScrollNotify ( (U32)flagl5) 

Messages Defined by Other Classes 



msgNewDefaults 

Initializes the NEW structure. 

Takes P_TV_NEW, returns STATUS. Category: class message. 

Comments Zeros out pNew->tv and sets: 

tv. style. flags = tvsWordWrap; 
tv. flags = tvFillWithIP; 



lenfs 
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win. flags. Style |= wsGrowBottom | wsSendFile | 

wsSendGeometry | wsCaptureGeometry; 
win. flags. style &= ~ (wsSendLayout | wsCaptureLayout) ; 
win . flags . input |= inputMoveDown | inputMoveDelta | 

inputHoldTimeout | inputOutProx | 

inputTip I inputEnter | inputExit; 
view.createDataObject = true; 
gWin.helpId = tagTextView; 

msgNew 

Creates a new instance of clsTextView. 

Takes P_TV_NEW, returns STATUS. Category: class message. 

If pArgs->view.createDataObject is true, then the textView creates a Text data object (clsText; see 
txtdata.h) and sets the view's data object If pArgs->tv.dc is NULL the textView creates a DC for its 
exclusive use. 



msgGWinXList 

Defined in gwin.h. 

Takes P_XLIST, returns STATUS. 

In response to this message, a textView typically performs some editing operation on its associated data 
object. A textView can process both "vanilla" xlists as described in xlist.h or text-specific xlists as 
txtxlist.h. 

Here's how a textView responds to each xlist element: 

xtBounds remembers the bounds of a gesture element 

xtGesture processes the gesture 

xtText inserts the text 

xtObject embeds the object 

xtCharAttrs modifies the character attributes of the specified characters 

xtParaAttrs modifies the attributes of the specified paragraphs 

xtTabs modifies the tabs of the specified paragraphs 

xtCharPos sets the insertion point for text to the specified character position 



Messages 



msgTextViewAddIP 

Adds an insertion pad to the textView. 

Takes P_TV_EMBED_METRICS, returns STATUS. 
#define msgTextViewAddIP TVMakeMsg(O) 

lessage typedef struct TV_EMBED_METRICS { 

.rgumenis TEXT_INDEX pos; // In: embedded object is inserted 

// just before this position. 
U16 flags; // One of the values below 

OBJECT embedded; // In-Out: the UID of the embedded object 

} TV_EMBED_METRICS, *P_TV_EMBED_METRICS ; 

onimenfs The client must set all of the fields of pArgs as described in the discussion of TV_EMBED_METRICS. 
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Zomine-nts 



msgTextViewCheck 

A textView performs a self-consistency check. 

Takes P_UNKNOWN, returns STATUS. 

♦define msgTextViewCheck TVMakeMsg(5) 

This message is only available in the debugging version oftext.dll. The only currently defined value for 
pArgs is zero. 

stsOK no problems detected 

< StsOK problems detected 



msgTextViewEmbed 

Embeds an object in the textView. Makes associated changes in text data. 
Takes P_TV_EMBED_METRICS, returns STATUS. 
♦define msgTextViewEmbed TVMakeMsg(l) 

typedef struct TV_EMBED_METRICS { 

TEXT_INDEX pos; // In: embedded object is inserted 

// just before this position. 
U16 flags; // One of the values below 

OBJECT embedded; // In-Out: the UID of the embedded object 

} TV_EMBED_METRICS, *P_TV_EMBED_METRICS; 

The client must set all of the fields of pArgs as described in the discussion of TV_EMBED_METRICS. 

msgTextViewGetEmbedMetrics 

Passes back the textView-specific metrics for an embedded object. 

Takes P_TV_EMBED_METRICS, returns STATUS. 

♦define msgTextViewGetEmbedMetrics TVMakeMsg(2) 

typedef struct TV_EMBED_METRICS { 

TEXT_INDEX pos; // In: embedded object is inserted 

// just before this position. 
U16 flags; // One of the values below 

OBJECT embedded; // In-Out: the UID of the embedded object 

} TV_EMBED_METRICS, *P_TV_EMBED_METRICS; 

The client need only fill in pArgs->embedded. 



msgTextViewRepair 

Forces a delayed paint operation to take place immediatelj/^. 

Takes pNull, returns stsOK. 

♦define msgTextViewRepair TVMakeMsgO) 

Use with caution, as overuse of this message significantly degrades performance. 



msgTextViewResolveXY 

Given an point in LWC space, passes back the character at (or near) the point. 

Takes P_TV_RESOLVE, returns STATUS. 

♦define msgTextViewResolveXY TVMakeMsg{4) 



Message 
Argymenfs 



Comments 



tefyrrs Value 



Argymenfs 
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typedef struct TV RESOLVE { 



XY32 


xy; 


U16 


flags; 


TEXT_INDEX 


pos; 


TEXT_INDEX 


lineStart; 


S8 


xRegion; 


S8 


yRegion; 


TEXT INDEX 


selects; 


XY32 


offset; 


P UNKNOWN 


spares [4] ; 



// In: Out: Units are LWC 
// One of the values below 
// Out: Pos of char containing xy, or 
// maxTEXT_INDEX if no such char 
// Out: Pos of first char on line 
//containing xy, or maxTEXT_INDEX 
// if no line contains xy. 
// Out: Region x was in. See diagram. 
// Out: Region y was in. See diagram. 
// Out: Pos of char "selected" by xy 
// Out: Offset to prev/next char's ink 
// Reserved. 
} TV_RESOLVE, *P_TV_RESOLVE; 

pArgs->flags control exactly which character is "selected", and how much information is provided by the 
message. 

Clients can also use this message to "reverse resolve" as follows. If both pArgs->}9^.x and pArgs->xy.y are 
maxS32, then the textView sets pArgs->xy to the coordinates of the lower left corner of the character at 
pArgs->pos. 

Warning: The response to this message always updates pArgs->xy to reflect information about the line 
either containing (or near) the original xy (or pos). 

"LWC" is short for Local Window Coordinates. See win.h for more information. 

stsBadParam if no line's y extents include pArgs->xy.y 

stsNoMatch if a containing line exists but it has no character under pArgs->xy.x; of if reverse resolve of 
a character not contained in any display line 



msgTextViewScroU 

Repositions displayed text within the textView. 

Takes P_TV_SCROLL, returns stsOK. 

#define msgTextViewScroll TVMakeMsg(6) 



typedef struct TV_SCROLL { 
TEXT_INDEX pos; 

U32 flags; 

} TV SCROLL, *P TV SCROLL; 



// Position to scroll to 
// One of the values below 



The client must set the fields of pArgs as described in the discussion of TV_SCROLL. 



mssQQe 
^rgymeofs 



msgTextViewGetStyle 

Passes back a textView s style. 

Takes P_TV_STYLE, returns stsOK. 

#define msgTextViewGetStyle TVMakeMsg{8) 



typedef struct TV_STYLE { 
U16 flags; 

S8 magnification; 



U8 



showSpecial; 



OBJECT printer; 
} TV STYLE, *P TV STYLE; 



// One of the values below 

// when tvsFormatForPrint is not on, this 

// value (in points) is added to the 

// character font sizes. 

// 0: show no special characters. 

// 1: undefined — do not use. 

// 2: undefined — do not use. 

// 3: show all special characters. 

// (6 spare bits) 

// Not implemented. Should be null. 
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msgTextViewSetSelection 

Selects one or more characters displayed by the textView. 

Takes P_TV_SELECT, returns stsOK. 

tdefine msgTextViewSetSelection TVMakeMsg(9) 

AessoQe typedef struct TV_SELECT { 

Irgumenfs TEXT_INDEX first; // lpoTEXT_INDEX means "clear selection" 

TEXT INDEX length; // results in an length selection 



U16 flags 

ATOM level 

} TV SELECT, *P TV SELECT 



// either or wsSynchRepaint (see win.h) 
// Obsolete. Don't use. 



lommenfs The fields of pArgs are used as follows: 

first The first character to select. The value lpoTEXT_INDEX means that cause the selection to be 
cleared. 

length Number of characters to select. The value results in a zero-length I-Bean selection. 

flags if this field is wsSynchRepaint (defined in win.h) the textVlew repaint immediately. Otherwise 
this field must be zero. 

While handling this message, the textView becomes the selection owner unless pArgs->first is 
lpoTEXT_INDEX, in which case the text view ensures that it is NOT the selection owner. 

msgTextViewSetStyle 

Sets a textView's style. 

Takes P_TV_STYLE, returns stsOK. 

#define msgTextViewSetStyle TVMakeMsg(lO) 

iessoge typedef struct TV_STYLE { 

Irgmnsnts U16 flags; // One of the values below 

S8 magnification; // when tvsFormatForPrint is not on, this 

// value (in points) is added to the 
// character font sizes. 
U8 showSpecial; // 0: show no special characters. 

// 1: undefined — do not use. 
// 2: undefined — do not use. 
// 3: show all special characters. 
// (6 spare bits) 
OBJECT printer; // Not implemented. Should be null. 

} TV_STYLE, *P_TV_STYLE; 

Zommenfs pArgs->printer should be set to Nil (OBJECT). 



Definitions for msgNew 



#ifndef NO_NEW 

tifndef txtViewNewFields 

#ifndef VIEW_INCLUDED 

tinclude <view.h> 

#endif 

See comment with msgNew and msgNewDefaults for more information. 

typedef struct TV_NEW_ONLY { 

U16 flags; // One of the values below 

OBJECT dc; 

TV_STYLE style; 
} TV NEW ONLY, *P TV NEW ONLY; 
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Use this in the flags field of a TV_NEW_ONLY. 

tdefine tvFillWithIP flagO 

tdefine txtViewNewFields \ 
viewNewFields \ 
TV_NEW_ONLY tv; 

typedef struct TV_NEW { 

txtViewNewFields 
} TV NEW, *P TV NEW; 



Utility Functions 



TextCreateTextScroUWin 

Utility function that creates a textView (with a data object) placed inside a scroll window. (See swin.h.) 

Returns STATUS. 

STATUS EXPORTED 

Function Prototype TextCreateTextScroUWin ( 
P_TV_NEW pNew, 
P_OBJECT scrollWin); // Out: 

tendif // txtViewNewFields 
#endif // NO_NEW 

Comments Clients often need a "vanilla" textView inside a vanilla scrollWin. This function does just that. Clients 

can modify the created objects after the creation if this function doesn't do quite the right thing. Client 
who need more control over the creation should probably create the objects manually. 

The pNew parameter should be null or should point at an already initialized NEW struct. If it is null, 
then the function creates a default instance of clsTextView. 

Because the view is created with formatForPrinter FALSE, the scroilWin's expandChildWidth is set to 
true. This causes the scrollWin to manage the width of the textView. 

Here's a simplified indication of how the scrollWin is created: 

ObjectCall(msgNewDefaults, clsScrollWin, &sn) 

sn. scrollWin. clientWin = <the text view> 

sn. scrollWin. style. vert Scrollbar = true; 

sn. scrollWin. style. autoVertScrollbar = false; 

sn. scrollWin. style. expandChildWidth = true; 

sn. scrollWin. style. expandChildHeight = true; 

sn. scrollWin. style. contractChildWidth = true; 

sn. scrollWin. style. contractChildHeight = true; 

sn. scrollWin. style. vertClient = swClientWin; 

sn. scrollWin. sty le.horizClient = swClientScrollWin; 

sn. win. flags. input |= inputHoldTimeout ; 

sn . scrollWin . style . forward = swForwardGesture; 

if (<creating on screen>) { 

sn . border . style . lef tMargin = bsMarginMedium; 

sn. border. style. rightMargin = bsMarginMedium; 

sn. border. style. topMargin = bsMarginMedium; 
} else { 

sn.border. style. lef tMargin = bsMarginNone; 

sn. border. style. rightMargin = bsMarginNone; 

sn.border. style. topMargin = bsMarginNone; 
} 

Ob jectCall (msgNew, clsScrollWin, &sn) ; 
*scrollWin = sn.object.uid; 

Warning: When printing, the scrollWin and textView are probably restored, not created anew. 
Therefore the client needs to go in and set the scroUWin's margins to 0. 
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TextIP 



typedef struct TEXTIP_METRICS { 

U16 flags; // Reserved. 

} TEXTIP_METRICS, *P_TEXTIP_METRICS, 
TEXTIP_NEW_ONLY, *P_TEXTIP_NEW_ONLY; 

msgNewDefaults 

Initializes the NEW struct. 

Takes P_TEXTIP_NEW, returns STATUS. Category: class message. 

In response to this message, ckTextlP does the following: 

pArgs->win. flags. style |= wsSendGeometry | wsSendFile i 

wsShrinkWrapHeight ; 
pArgs->ip.rows = 5; 

pArgs->ip. lines = 5; 

If the user input pad style preference is Boxed: 

pArgs->ip. style. displayType = ipsCharBox; 
pArgs->ip. style. delayed = 1; 

If the user input pad style preference is Ruled: 

pArgs->ip. style. displayType = ipsRuledLines; 

If the user input pad style preference is RuledAndBoxed: 

pArgs->ip. style. displayType = ipsRuledLines; 
pArgs->ip. style. ruledToBoxed = true; 

msgNew 

Creates a new instance of cIsTextlP. 

Takes P_TEXTIP_NEW, returns STATUS. Category: class message. 



msgTextlPGetMetrics 

Passes back a textIP s metrics. 

Takes P_TEXTIP_METRICS, returns stsOK. 

#define msgTextlPGetMetrics MakeMsg(clsTextIP, 1) 

typedef struct TEXTIP_METRICS { 

U16 flags; // Reserved. 

} TEXTIP METRICS, *P TEXTIP METRICS, 
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Arguments 



msgTextlPSetMetrics 

Sets a textlP's metrics. 

Takes P_TEXTIP_METRICS, returns stsOK. 



tdefine msgTextlPSetMetrics 

tifndef NO_NEW 

#ifndef textlPNewFields 

#ifndef 

♦include <insert.h> 

#endif 

#define textlPNewFields 

ipNewFields 

TEXTIP_NEW_ONLY 

typedef struct TEXTIP_NEW { 

textlPNewFields 
} TEXTIP_NEW, *P_TEXTIP_NEW; 

#endif // textlPNewFields 
tendif //NO NEW 



MakeMsg(clsTextIP, 2) 



INSERT INCLUDED 



\ 
\ 
text IP; 



Argi, 



typedef struct TEXTIP_METRICS { 

U16 flags; // Reserved. 

} TEXTIP METRICS, *P TEXTIP METRICS, 
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This file contains the Text subsystem additions to xUst (see xlist.h). 

A Text View (see txtView.h) gathers input directly fi^om the user via 

keyboard input delivered by msglnputEvent, with Cls(pArgs->devCode) == Cls(clsKey); 

low-level pen input also msglnputEvent, but Cls(clsPen); 

gestures delivered by msgGWinXlist; and 

insertion pads which provide data starting with msglPDataAvailable. 

The user input delivered to a Text View from an insertion pad is communicated via an xlist. As a result 
of its processing of the xlist, the Text View modifies its associated data object. Each xlist moves through 
the following stages: (1) it comes into being as a way for the hwx system to provide low-level 
information about the user input to clsIP (see insert.h); (2) clsIP packages the low-level information 
into medium-level information which is self-sent; (3) finally, clsTextlP re-interprets this information 
and packages it into high-level information which requires concepts specific to the Text subsystem. 
Thus, an xlist from a TextIP (see txtView.h) can contain one or more elements of the following 
specialized types. For each type, the constraint on the structure of the information pointed to by the 
pData field of the XLIST_ELEMENT is listed. 

xtCharAttrs pData points to an XLIST_CHAR_ATTRS; 

xtParaAttrs pData points to an XLIST_PARA_ATTRS; 

xtTabs pData points to an XLIST_TABS; 

xtCharPos pData is a TEXT_INDEX (cast to a P_UNKNOWN) . 

The types themselves are defined as part of XTYPE in xlist.h; the data structures and their semantics are 
defined below. 

In general, an xlist is position-independent. However, the caller of msgGWinXlist often wants the 
associated xlist to modify a Text View's data object beginning at a particular character index; an element 
of type XtCharPos allows the caller to specify such an index. 

To make it easier to maintain the position-independent property of an xlist. Text Views recognize 
maxTEXT_INDEX (see txtData.h) as having a special meaning when used as the value of the first field 
of the pData in an xlist element of type xtCharAttrs, xtParaAttrs and xtTabs (i.e., pData->first == 
maxTEXT_INDEX). If the pData->length is 0, a pData->first of maxTEXT_INDEX causes the xlist 
processing code to remember the current index in the Text data object and to take no other action; if the 
pData->length is non-zero, the pData->first of maxTEXT_INDEX causes the xlist processing code to 
update pData->first with the previously remembered index. This allows the caller of msgGWinXlist to 
generate an xlist with the following structure: 

XtCharPos to start processing at a particular index; 

xtText one or more times, to add characters; 

XtCharAttrs with first of maxTEXT_INDEX, length of 0; 

XtText one or more times, to add more characters; 
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xtCharAttrs with first of maxTEXTJNDEX, length not 0, thereby setting the character attributes for 
exactly the bracketed characters. 

#ifndef TXTXLIST_INCLUDED 
tdefine TXTXLIST_INCLUDED 

#ifndef XLIST_INCLUDED 
tinclude <xlist.h> 
#endif 

#ifndef TXTDATA_INCLUDED 
tinclude <txtData.h> 
#endif 

Upon encountering an xlist element of type xtCharAttrs, a Text View does a m^TextChangeAttrs to its 
data object, making use of the fields of the P_XLIST_CHAR_ATTRS by mapping them to the 
corresponding fields of TEXT_CHANGE_ATTRS as follows: 

tag forced to atomChar 

first copied from first 

length copied from length 

pNewMask set to &mask 

pNewValues set to &attrs 

typedef struct { 

TEXT_INDEX first; 

TEXT_INDEX length; 

TA_CHAR_MASK mask; 

TA_CHAR_ATTRS at t r s ; 

} XLIST_CHAR_ATTRS, *P_XLIST_CHAR_ATTRS; 

Upon encountering an xlist element of type xtParaAttrs, a Text View does a msgTextChangeAttrs to its 
data object, making use of the fields of the P_XLIST_PARA_ATTRS by mapping them to the 
corresponding fields of TEXT_CHANGE_ATTRS as follows: 

tag forced to atomPara 

first copied from first 

length copied from length 

pNewMask set to &mask 

pNewValues set to &attrs 

typedef struct { 

TEXT_INDEX first; 

TEXT_INDEX length; 

TA_PARA_MASK mask; 

TA_PARA_ATTRS at t r s ; 

} XLIST_PARA_ATTRS, *P_XLIST_PARA_ATTRS; 

Upon encountering an xlist element of type xtTabs, a Text View does a msgTextChangeAttrs to its data 
object, making use of the fields of the P_XLIST_TABS by mapping them to the corresponding fields of 
TEXT_CHANGE_ATTRS as follows: 

tag forced to atomParaTabs 

first copied from first 

length copied from length 

pNewMask set to Nil() 
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pNewValues set to &tabs 

typedef struct { 

TEXT_INDEX first; 

TEXT_INDEX length; 

TA_MANY_TABS tabs; 
} XLIST TABS, *P XLIST TABS; 
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FILETYPE.H 



This file defines common file types used for import and export between PenPoint and other operating 
systems. 

tifndef FILETYPE_INCLUDED 
tdefine FILETYPE_INCLUDED 

ttifndef GO_INCLUDED 
# include <go.h> 
#endif 

#ifndef UID_INCLUDED 
tinclude <uid.h> 
#endif 

The following file types are common enough to merit a central registry Contact GO Developer 
Technical Support if you want to add a file type to the registry 

The file types are defined as tags; they are primarily intended to be stored as the value of the 
fsAttrFilcType file attribute. If a file is explicitly typed via this mechanism, applications can more easily 
decide if they can import it. 

tdefine f ileTypeUndef ined ( (TAG) OL) 

fileTypeASCII implies 8-bit bytes encoding the 7-bit ASCII set defined by ANSI X3.64. Any byte with 
value greater than 0x7F will be interpreted in a manner dependent on the subsystem involved; e.g. 
clsText (and thus the MiniText application) will assume the bytes encode IBM-PC Code Page 850. 

#define fileTypeASCII MakeTag (clsFileHandle, 0) 

fileTypeASCIISoftLineBreaks is similar to fileTypeASCII, The difference is that in a line that has no 
explicit new line or carriage return, a space is transformed into a line feed near the 72nd character. 

tdefine fileTypeASCIISoftLineBreaks MakeTag (clsFileHandle, 1) 

fiieTypeRTF implies Microsoft Corporation's Rich Text Format (RTF). 

tdefine fiieTypeRTF MakeTag (clsFileHandle, 2) 

fileTypeTIFF implies Aldus Corporation and Microsoft Corporation's Tag Image File Format (TIFF). 

tdefine fileTypeTIFF MakeTag (clsFileHandle, 3) 

fileTypePicSeg implies Go Corporation's Picture Segment format. 

tdefine fileTypePicSeg MakeTag (clsFileHandle, 4) 



FS.H 






This file contains the API for clsDirHandle and clsFileHandle. The functions described in this file are 
contained in PENPOINT.LIB. 

clsFileSystem inherits from clsObject. 

Provides file system support. theFileSystem is the only instance of clsFileSystem. 

clsDirHandle inherits from clsObject. 

Provides file system directory support. theBootVolume is a well known instance of clsDirHandle. 
theSelectedVolume is a well known instance of clsDirHandle. theWorkingDir is a well known instance 
of clsDirHandle. 

clsFileHandle inherits from clsStream. 

Provides file system file access support. 

#ifndef FS_INCLUDED 
tdefine FS INCLUDED 



Debugging Flags 



FileSystem Debugging Flag is '$', values are: 

0001 Debug info when fs cache layer calls volume layer 

0200 Breaks into debugger before asking to insert disk 

20000 Display list of known volumes when prompting for unmounted disk 

Include file dependencies for this include file 

tifndef GO_INCLUDED 
#include <go.h> 
#endif 

#ifndef UID_INCLUDED 

#include <uid.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

#endif 

tifndef UUID_INCLUDED 

tinclude <uuid.h> 

tendif 

tifndef STREAM_INCLUDED 
tinclude <stream.h> 
tendif 

Common abbreviations, terms: 
FS File System 
Node A file or a directory 
Dir A directory 
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Rules concerning the destination of file system messages: 

All messages defined in this file are directed to their destination via ObjectCall, the file system does not 
accept messages that are sent. All messages (with the exception of msgFSGetlnstalledVolumes) of 
cisFileSystem can be "sent" to either a file or a dir object. Messages of clsDirHandle can only be "sent" 
to directory objects. Messages of clsFileHandle can only be "sent" to file objects. 



Common #defines and iypedefs 

Defines 



♦define fsMaxPathLength 



254 



// Max path length 

// (Excluding null terminator) 



tdefine 
fdefine 
tdefine 
#define 
#define 
tdefine 
tdefine 
tdefine 



fsPathBufLength (fsMaxPathLength+1) // Buffer size for max path 



fsSeparator 

fsEscapeChar 

fsUniqueSeparator 

fsMaxHandles 

fsMaxUnique 

fsMaxReadWrite 

f sMaxNe s t ingLe ve 1 



'W // Pathname separator 

' r // Escape char (invalid in paths) 

' ' // Char for unique name postfix 

255 // Max handles on a single node 

255 // Max tries to make name unique 
0x40000000 // Max size for single read/write 

20 // Max nesting for recursive ops 



FS Attribute Intrinsics 



These are used to build file/directory attribute labels or to get component pieces from an attribute label. 

A client can define their own attribute using one of the FSMakeXXXAttr intrinsics, specifying a class 
and a tag. The attribute type will allow for storage of a 32 bit value (Fix32), a 64 bit value (Fix64), a null 
terminated string of any length up to 32K (Str), or a variable length value up to 32K (Var). The 
messages msgFSGetAttr, msgFSSetAttr, msgFSReadDir, msgFSReadDirFull and msgFSTraverse use 
file system attributes to represent the attribute label. 

tdefine fsFixAttr 

tdefine fsFix64Attr 1 

tdefine fsVarAttr 2 

tdefine fsStrAttr 3 

tdefine fsMaxAttrLength 255 

tdefine FSMakeAttr(cls,t,f) \ 

MakeTagWithFlags (els, t, f ) 



tdefine FSMakeFix32Attr(cls,t) 
tdefine FSMakeFix64Attr(cls,t) 
tdefine FSMakeVarAttr(cls,t) 
tdefine FSMakeStrAttr(cls,t) 
tdefine FSAttr(attr) 
tdefine FSAttrCls (attr) 
tdefine FSAttrIsFix32 (attr) 
tdefine FSAttrIsFix64 (attr) 
tdefine FSAttrlsVar(attr) 
tdefine FSAttrlsStr (attr) 



FSMakeAttr (els, t, fsFixAttr) 

FSMakeAtt r (els , t , f sFix64Att r ) 

FSMakeAttr (els, t , fsVarAttr) 

FSMakeAttr (els, t, fsStrAttr) 

TagNum(attr) 

ClsNum(attr) 

(TagFlags (attr) == fsFixAttr) 

(TagFlags (attr) == f sFix64Attr) 

(TagFlags (attr) == fsVarAttr) 

(TagFlags (attr) == fsStrAttr) 



File System Attributes 

These are the predefined attributes managed by the file system. 



tdefine fsNu 11 Attr Label 
tdefine fsAttrName 
tdefine fsAttrFlags 
tdefine fsAttrDateCreated 
tdefine fsAttrDateModified 
tdefine fsAttrFileSize 



FSMakeFix32Attr (ob jNull, 0) 

FSMakeStrAttr (clsFileSystem, 0) 

FSMakeFix32Attr (clsFileSystem, 0) 
FSMakeFix32Attr (clsFileSystem, 2) 
FSMakeFix32Attr (clsFileSystem, 3) 
FSMakeFix32Attr (clsFileSystem, 4) 
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tdefine fsAttrDirlndex 
Idefine fsAttrOldDirlndex 
#define fsAttrFileType 



FSMa]ceFix64Attr{clsDirHandle, 0) 
FSMakeFix64Attr(clsDirHandle, 1) 
FSMakeFix32Attr (clsFileHandle, 0) 



See msgFSGetAttr for an explanation when to use these constants. 

tdefine fsAllocAttrLabelsBuffer ( (P_FS_ATTR_LABEL)maxU32) 
#define fsAllocAttrValuesBuffer { (P_UNKNOWN)maxU32) 
♦define fsAllocAttrSizesBuffer ( (P FS ATTR SIZE)maxU32) 



Status Codes 



Common return values: 

There are a few status return values that are common to either all messages or to a group of messages 
(i.e. messages that try to change the volume). 

stsFSHandlelnvalid The dir/file object refers to a node that has been previously deleted. 

stsFSVolDisconnected The volume is not connected. 

stsFSVolFull The message cannot complete, due to insufficient space on the volume. 

stsFSVolReadOnly The message cannot complete, because the volume is write protected. 

Error Status Codes 



tdefine stsFSVolDisconnected MakeStatus 

tdefine stsFSVolReadOnly MakeStatus 

tdefine stsFSVolFull MakeStatus 

tdefine stsFSNodeNotFound MakeStatus 

tdefine stsFSNodeReadOnly MakeStatus 

tdefine stsFSAccessDenied MakeStatus 

tdefine stsFSCircularMoveCopy MakeStatus 

tdefine stsFSVolBusy MakeStatus 

tdefine stsFSNodeBusy MakeStatus 

tdefine stsFSBadPath MakeStatus 

tdefine stsFSUniqueFailed MakeStatus 

tdefine stsFSDirFull MakeStatus 

tdefine stsFSNodeExists MakeStatus 

tdefine stsFSNotDir MakeStatus 

tdefine stsFSNotFile MakeStatus 

tdefine stsFSReadOnlyAttr MakeStatus 

tdefine stsFSBufTooSmall MakeStatus 

tdefine stsFSNestingTooDeep MakeStatus 

tdefine stsFSNoParent MakeStatus 

tdefine stsFSUnchangeable MakeStatus 

tdefine stsFSNotAncestor MakeStatus 

tdefine stsFSDirPositionLost MakeStatus 

tdefine stsFSHandlelnvalid MakeStatus 

tdefine stsFSDifferent MakeStatus 

tdefine stsFSTooManyHandles MakeStatus 

tdefine stsFSDirlndexExists MakeStatus 

tdefine stsFSDirlndexNotFound MakeStatus 

tdefine stsFSVolCorrupt MakeStatus 

Informational Status Codes 



(clsFileSystem, 0) 
(clsFileSystem, 1) 
(ClsFileSystem, 2) 
(clsFileSystem, 3) 
(clsFileSystem, 4) 
(ClsFileSystem, 5) 
(clsFileSystem, 6) 

(clsFileSystem, 7) 
(clsFileSystem, 8) 
(clsFileSystem, 9) 
(ClsFileSystem, 10) 
(clsFileSystem, 11) 

(ClsFileSystem, 12) 
(ClsFileSystem, 13) 
(clsFileSystem, 14) 
(ClsFileSystem, 15) 
(clsFileSystem, 16) 
(clsFileSystem, 17) 

(ClsFileSystem, 18) 
(ClsFileSystem, 19) 
(ClsFileSystem, 20) 
(ClsFileSystem, 21) 
(ClsFileSystem, 22) 
(ClsFileSystem, 23) 
(clsFileSystem, 24) 

(ClsFileSystem, 25) 
(ClsFileSystem, 26) 

(ClsFileSystem, 27) 



tdefine stsFSAttrBufTooSmall MakeWarning (clsFileSystem, 1) 
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Types 



Locators are structures used to describe the location of a file or dir node. There are two types of locators: 
explicit and implicit. An explicit locator is defined with FS_LOeA.TOR which specifies both the starting 
node (uid) and the path relative to the starting node (pPath). An implicit locator is made up of a 
starting node (the object that receives a message) and the path relative to the starting node (pPath). 
msgFSMove is a good example of a message that contains both types of locators. The receiver of 
msgFSMove and move.pSourcePath defines the implicit location of the source of the move. 
move.destLocator defines the explicit location of the dest of the move. 

The uid field of a locator must be filled in and must be non-null. If no other choice can be decided 
upon, theWorkingDir may be a good one. The uid field does not always have to be a dir handle object. 
The uid can be a file handle object if the pPath field points to a path that begins with .. (parent), \ (root) 
or W (fiilly specified path including volume name). 

The path field of locators (explicit and implicit) are relative to the node defined by the uid (or object 
receiving the message) unless the path begins with a \ (root relative) or W (fully specified path). 

typedef struct FS_LOCATOR { 

OBJECT uid; 

P_STRING pPath; // Relative to node defined by uid 

} FS_LOCATOR, * P_FS_LOCATOR; 

The file system interface never uses flat locators, but if it is more convenient to hold the entirety of the 
locator in a linear structure using flat locators. 

typedef struct FS_FLAT_LOCATOR { 

OBJECT uid; 

U8 path [fsPathBuf Length]; 

} FS_FLAT_LOCATOR, * P_FS_FLAT_LOCATOR; 
Enuml6(FS_N0DE_FLAGS) { 

fsNodeReadOnly = flagO, // Node is read-only. 

fsNodeHidden = flagl, // System hidden file. 

fsNodeDir = flag4, // Directory or file? 

fsNodeGoFormat = flagS, // Node has non-native attrs 

fsNodePenPoint Hidden = flag9 // Should this node be hidden from 

// the user in Penpoint browsers? 
}; 
#define validFSNodeFlags \ 

(fsNodeReadOnly | fsNodeHidden | fsNodeDir | \ 
fsNodeGoFormat | fsNodePenPointHidden) 

#define readOnlyFSFlags (fsNodeDir | fsNodeGoFormat) 

FS_NODE_FLAGS_ATTR is used to set or get the flags attribute stored with a file/dir node. When setting 
the flags, only those flags with a one in the mask word will be affected. When getting flags, all flags are 
returned and mask is set to all ones (as a convenience for set after get). 

typedef struct FS_NODE_FLAGS_ATTR { 

FS_NODE_FLAGS flags; 

U16 mask; 

} FS_NODE_FLAGS_ATTR, * P_FS_NODE_FLAGS_ATTR; 

typedef U32 FS_DATE_TIME, * P_FS_DATE_TIME ; 
typedef U32 FS_FILE_SIZE, * P_FS_FILE_SIZE; 

typedef U16 FS_ATTR_SIZE, * P_FS_ATTR_SIZE; 
typedef U32 FS_ATTR_LABEL, * P_FS_ATTR_LABEL; 

Enuml6(FS_V0L_TyPE) { 

fsAnyVolType =0, // Match any vol type for msgNew 

fsVolTypeMemory = 0, 

fsVolTypeDisk =1, 

fsVolTypeRemote = 2 
}; 
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Enuml6(FS_V0L_FLAGS) { 

fsVolReadOnly = flagO, 

fsVolConnected = flagl, 

fsVolRemovableMedia = flag2, 

fsVolEjectableMedia = flag3, 

fsVolDirsIndexable = flag4, 

fsVolFormattable = flagS, 

fsVolDuplicatable = flag6 
}; 

This information is returned by msgFSGetVolMetrics. 

typedef struct FS_VOL_HEADER { 



FS_VOL_ 


TYPE 


type; 




FS_VOL_ 


FLAGS 


flags; 




OBJECT 




rootDir; 




OBJECT 




volObj; 




U32 




serialNum; 




U32 




created; 




U16 




optimalSize; 




U32 




totalBytes; 




U32 




freeBytes; 




U32 




commSpeed; 




U8 




pName [nameBufLength] ; 


U8 




alignSpare; 


// Wor 


CLASS 




browserClass; 


// Cla 
// If 


U32 




nativeFS; 




RES ID 




iconResId; 




U32 




spare 1; 




U32 




spare2 ; 




U32 




spare 3; 




U32 




spare4; 




} FS VOL HEADER, 


* P FS VOL HEADER; 





// Word align following values 

// Class of browser to use for volume 

// If null, use system default 



typedef FS_VOL_HEADER FS_VOL_METRICS, * P_FS_VOL_METRICS ; 

Enuml6(FS_EXIST) { 
// Lower byte: what to do if the node exists 

fsExistOpen = 0, 

fsExistGenError = 1, 

fsExistGenUnique = 2, 

fsExistTruncate = 3, 
// Upper byte: what to do if the node doesn't exist 

fsNoExistCreate =MakeU16(0, 0), 

fsNoExistGenError =MakeU16(0, 1), 

fsNoExistCreateUnique = MakeUl6(0, 2), 
// Default setting 

fsExistDefault = fsExistOpen | fsNoExistCreate 
}; 

Enuml6{FS_M0VE_C0PY_EXIST) { 
// What to do if the destination node exists 



fsMoveCopyExi St Overwrite 
fsMoveCopyExistGenError 
fsMoveCopyExistGenUnique 
fsMoveCopyExistDelete 
// Default setting 

fsMoveCopyExistDefault 



= 0, 

= 1, 

= 2, 

= 3, 

= fsMoveCopyExistGenError 



}; 
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Enuml 6 (FS_DIR_NEW_MODE ) { 
// Delete directory at handle free time? 

fsTempDir = flagO, 
// Is handle changeable? 

fsUnchangeable = flagl, 
// Find node via its dir index? 

fsUseDirlndex = flag2, 
// Disable prompts (insert disk, write protected, etc) 
// fsDisablePrompts = flag4, (Defined in FS_FILE_NEW_MODE below) 
// System owned dir handle - ring only 

fsSystemDir = flag?, 
// Default setting 

fsDirNewDefaultMode = // permanent, changeable directory 
}; 

Enuml6(FS_FILE_NEW_M0DE) { 
// Lower byte: flags 
// Delete file at handle free time? 

fsTempFile = flagO, 
// Read/write intentions for this handle 

fsReadOnly = flag2, 
// Memory mapped files accessibility 

fsSharedMemoryMap = flag3, 
// Disable prompts (insert disk, write protected, etc) 

fsDisablePrompts = flag4, 
// System owned file handle - ring only 

fsSystemFile = flagV, 
// Upper byte: exclusivity requirements for other handles 

fsNoExclusivity = MakeUl6(0, 0), 

fsDenyWriters =MakeUl6(0, 1), 

fsExclusiveOnly =MakeUl6(0, 2), 
// Default setting 

fsFileNewDefaultMode= // perm, read/write (noExclusivity) 
}; 

Enuml 6 (FS_GET_PATH_MODE ) { 
// Get path relative to root, dir passed in, just name or vol and path 

fsGetPathRoot = 0, 

fsGetPathRelative = 1, 

fsGetPathName = 2, 

fsGetPathAbsolute = 3, 
// Default setting 

fsGetPathDefaultMode= fsGetPathRoot 
}; 

Enuml 6 (FS_MOVE_COPY_MODE ) { 
// Use destination as container. 

fsMoveCopylntoDest = flagO, 
// Check but don't move or copy. 

fsMoveCopyVerifyOnly = flagl, 
// Does source have live dir indexes. 

fsMoveCopySourceArchived = flag2, 
// Does dest have live dir indexes. 

fsMoveCopyArchiveDest = flagS, 
// Default setting 

fsMoveCopyDefaultMode = 
}; 

Enuml6{FS_TRAVERSE_M0DE) { 
// Call back on files? 

fsCallBackOnFiles = flagO, 
// Call back before stepping into directory? 

fsCallBackPreDir = flagl, 
// Call back after stepping into directory? 

fsCallBackPostDir = flag2, 
// Default setting 

fsTraverseDefaultMode= fsCallBackOnFiles I fsCallBackPreDir 
}; 
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Enuml6{FS_SEEK_M0DE) { 
// Relative to beginning of file, end of file, or Current Byte Position 

fsSeekBeginning = 0, 

fsSeekEnd = 1, 

fsSeekCurrent =2, 
// Default setting 

fsSeekDefaultMode = fsSeekBeginning 
}; 

typedef OBJECT DIR_HANDLE, * P_DIR_HANDLE; 

typedef OBJECT FILE_HANDLE, * P_FILE_HMDLE; 
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msgFSGetlnstalledVolumes 

Returns list of all installed volumes. 

Takes P_LIST, returns STATUS. 

tdefine msgFSGetlnstalledVolumes MakeMsg(clsFileSystem, 21) 

merits This message can only be directed to the well known class theFileSystem. Each object in the list is a 

directory handle object that references the root node of the volume. The list is passed back and is not 
used as an input parameter. The caller must free the returned list when finished using it, but do not free 
any of the objects in the list. 

Also msgFSEjectMedia to eject media from a floppy drive. 

msgFSGetVolMetrics to get more info about the volume 

msgFSSame to compare root dir to a well-known dir handle 

Class File System Messages understood by 
dirHandles and fileHandles 



Argyments 



msgNew 

Creates a directory or file handle object on a new or existing dir/file. 
Takes P_FS_NEW, returns STATUS. Category: class message. 



typedef struct FS_NEW_ONLY { 



FS_LOCATOR 

FS_VOL_TYPE 

UUID 

U16 

FS_EXIST 

P UNKNOWN 



locator; 
volType; 
dir Index; 
mode ; 
exist; 
pVolSpecific; 



U32 sparel; 

U32 spare2; 

BOOLEAN alreadyExisted; 

} FS NEW ONLY, * P FS NEW ONLY; 



// location of the target directory 

// hint for uninstalled fullpath vols 

// used with fsUseDirlndex mode only 

// options for opening file/dir handle 

// action to take if exists or doesn't 

// volume specific information 

// Note: this is an in only parm 

// for future use 

// for future use 

// Out: indicates if already exists 



tdefine fsNewFields 
objectNewFields 
FS_NEW_ONLY 

typedef struct FS_NEW 

fsNewFields 
} FS NEW, * P FS NEW; 



\ 
\ 
fs; 
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The fields you commonly set are: 

pNew->fs.locator Location of the node 

pNew->fs.mode Options for opening file/dir handle 

pNew->fs. exist Action to take if the file/dir exists or doesn't exist 

Accessing a directory using a dirlndex: Three pieces of information must be provided to open a 
directory by dirlndex. The fsUseDirlndex flag must be set in new. fs. mode, a valid dirlndex must be 
supplied in new.fs.dirlndex and the volume that the directory resides on must be identified. This can be 
done by specifying some location on the. volume by filling in new.fs.locator. Either the uid can point to 
the root or any other handle on the volume or the path can be an absolute path that identifies the 
volume. See msgFSSetAttr on how to store a dir index with a directory so it can later be accessed by its 
dir index. 

Use FS_DIR_NEW_MODE for mode if new is for dir handle. Use FS_FILE_NEW_MODE for mode if new is 
for file handle. 

stsBadParam locator.uid is not a valid object. 

stsFSAccessDenied Access cannot be granted because node is locked for exclusive access, read only 
access or write only access. 

stsFSBadPath locator.pPath is malformed or a specified dir node is in fact a file. 

stsFSDirFull There is no space in the dir for a new node. 

stsFSDirlndexNotFound There is not a dirlndex for the dir node. 

stsFSNodeBusy Node cannot be deleted/truncated because it is being access by another client. 

stsFSNodeExists The requested node already exists. 

stsFSNodeNotFound The root node does not exist. 

stsFSNodeReadOnly Node cannot be deleted/truncated or read/write access has been denied because 
the read only flag is set on the node. 

stsFSNotDir A requested dir node already exists as a file. 

stsFSNotFile A requested file node already exists as a dir. 

stsFSTooManyHandles There are already fsMaxHandles on this node. 

stsFSUniqueFailed fsMaxUnique variants of the name already exist. 

FSNameValid 

msgNewDefaults 

Initializes the FS_NEW structure to default values. 

Takes P_FS_NEW, returns STATUS. Category: class message. 

s$«ge typedef struct FS_NEW { 

Itjmenfs fsNewFields 

} FS_NEW, * P_FS_NEW; 

nments Zeroes out pNew->fs and sets: 



pNew->fs. locator. uid = theWorkingDir; 
pNew->object.cap |= objCapCall; 
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msgDestroy 

Destroys a directory or file handle. 

Takes OBJ_KEY, returns STATUS. 

Comments This destroys the handle, NOT the actual node. An exception to this is if the fsTempFile/fsTempDir 

flag was set in pNew->fs.mode when the handle was created. 

Refym ¥aiue stsFSNodeBusy Temporary node cannot be deleted because it is being access by another client. 

stsFSNodeReadOnly Temporary node cannot be deleted because the read only flag is set on the node. 



msgFSNull 

Does nothing. 

Takes void, returns STATUS. 

#define msgFSNull MakeMsg(clsFileSystem, 20) 

This message is used to time entering and exiting the file system. 

msgFSGetVolMetrics 

Returns metrics of the volume. 

Takes P_FS_GET_VOL_METRICS, returns STATUS. 

#define msgFSGetVolMetrics MakeMsg{clsFileSystem, 22) 

krQum&nts typedef struct FS_GET_VOL_METRICS { 

BOOLEAN updatelnfo; // have volume recompute values? 

FS_VOL_METRICS volMetrics; // Out: the volume's metrics 
} FS_GET_VOL_METRICS, * P_FS_GET_VOL_METRICS; 

leimn Value stsFSVolDisconnected This will never be returned, even if the volume is disconnected. Instead test 

fiiVolConnected in volMetrics.flags. 

You must set updatelnfo to TRUE if you want the volMetrics.freeBytes field or the fsVolConnected 
flag of the volMetrics.flags field to be updated before returning the vol metrics. Setting updatelnfo to 
FALSE will make this request faster, but these fields may not be correct. 

msgFSSetVolName 

Changes the name of a volume. 

Takes P_STRING, returns STATUS. 

tdefine msgFSSetVolName MakeMsg(clsFileSystem, 36) 

istmn ¥oiye stsBadParam New vol name is invalid (checked by FSNameValid). 

stsFSHandlelnvalid The dir/file object refers to a node that has been previously deleted. 

StsFSVolDisconnected The volume is not connected. 

stsFSVolReadOnly The new volume name cannot be set, because the volume is write protected. 
iee Also FSNameValid Mechanism to precheck validity of new volume name. 
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msgFSNodeExists 

Tests the existence of a file or directory node. 

Takes P_FS_NODE_EXISTS, returns STATUS. 

♦define msgFSNodeExists MakeMsg{clsFileSystem, 37) 

Argymenfs typedef struct FS_NODE_EXISTS { 

P_STRING pPath; // path to node that may exist 

BOOLEAN isDir; // Out: dir or file 

} FS_NODE_EXISTS, * P_FS_NODE_EXISTS; 

Comments The return parm isDir is useful in deciding whether the msgNew, to create a handle to the node, should 

be sent to dsDirHandle or clsFileHandle. The parm pPath is relative to the object that receives this 
message. 

iefyrn ¥ai«e stsOK The node exists. 

stsFSNodeNotFound The node does not exist. 

msgFSGetHandleMode 

Returns the "new" mode for the object's fs handle. 

Takes P_U16, returns STATUS. 

#define msgFSGetHandleMode MakeMsg(clsFileSystem, 23) 

Directory handles interpret the P_U16 as a P_FS_FILE_NEW_MODE. File handles interpret the P_U16 as a 
P FS DIR NEW MODE. 



msgFSSetHandleMode 

Changes the "new" mode for the object's fs handle. 

Takes P_FS_SET_HANDLE_MODE, returns STATUS. 

tdefine msgFSSetHandleMode MakeMsg(clsFileSystem, 24) 

typedef struct FS_SET_HANDLE_MODE { 

U16 mode; // value of mode flags to change 

U16 mask; // which mode flags are to change 

} FS_SET_HANDLE_MODE, * P_FS_SET_HANDLE_MODE; 

Directory handles interpret mode as a FS_FILE_NEW_MODE. File handles interpret mode as a 
FS DIR NEW MODE. 



msgFSSame 

Tests if another directory or file handle references the same node. 

Takes OBJECT, returns STATUS. 

#define msgFSSame MakeMsg(clsFileSystem, 25) 



msgFSGetPath 

Gets the path to (or name of) a directory or file handle node. 

Takes P_FS_GET_PATH, returns STATUS. 

#define msgFSGetPath MakeMsg(clsFileSystem, 26) 
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Argyments typedef Struct FS_GET_PATH { 

FS_GET_PATH_MODE mode; // options for get path operation 

DIR_HANDLE dir; // In-Out: rel dir or root dir 

U16 bufLength; // length of pPathBuf 

P_STRING pPathBuf; // Out: user buffer for path 

} FS_GET_PATH, * P_FS_GET_PATH; 

Comments If mode IS fsGctPathRoot or fsGetPathAbsolute the root dir handle is passed back in dir. If mode is 

fsGetPadhiRelative the path passed back begins at the dir represent by dir and terminates at the node 
represented by the recipient of this client. 

Return Voloe stsFSBufTooSmail User supplied pPathBuf is not large enough. 

stsFSNotAncestor dir is not ancestor of recipient of msgFSGetPath. 

msgFSGetAttr 

Gets an attribute or attributes of a file or directory node. 
Takes P_FS_GET_SET_ATTR, returns STATUS. 

tdefine msgFSGetAttr MakeMsg(clsFileSystem, 27) 

Arguments typedef struct FS_GET_SET_ATTR { 

P_STRING pPath; // path to node to get/set attrs 

U16 numAttrs; // number of attrs of interest 

P_FS_ATTR_LABEL pAttrLabels; // In-Out: attr labels 

P_UNKNOWN pAttrValues; // In-Out: attr values 

P_FS_ATTR_SIZE pAttrSizes; // In-Out: attr sizes 

} FS_GET_SET_ATTR, * P_FS_GET_SET_ATTR; 

Comments Specify which attributes you wish returned via an array of attribute labels pointed to by pAttrLabels. 

The number of attribute labels is specified by numAttrs. The values are passed back via an array of 
values. If the nth value represents a string or variable attribute a pointer must be filled in for the 
destination of the string/variable. If the nth value represents a Fix64 provide space for two consecutive 
U32s. The sizes are passed back via an array of sizes. 

If either the values are of no interest or the sizes are of no interest, set pAttrValues to pNull and/or set 
pAttrSizes to pNull. 

If you want all attributes of a node, but do not know what they may be set numAttrs to maxUl6, 
pAttrLabels to fsAliocAttrLabelsBuffer, and pAttrValues to fsAllocAttrValuesBuffer (or pNull if 
unwanted) and pAttrSizes to fsAllocAttrSizesBuffer (or pNull if unwanted). Any buffers returned as a 
result of fsAllocXXXBufFer must be freed with OSHeapBlockFree. 

The parm pPath is relative to the object that receives this message. 

msgFSSetAttr 

Sets the attribute or attributes of a file or directory node. 

Takes P_FS_GET_SET_ATTR, returns STATUS. 

#define msgFSSetAttr MakeMsg(clsFileSystem, 28) 

Messoge typedef struct FS_GET_SET_ATTR { 

Arguments P_STRING pPath; // path to node to get/set attrs 

U16 numAttrs; // number of attrs of interest 

P_FS_ATTR_LABEL pAttrLabels; // In-Out: attr labels 

P_UNKNOWN pAttrValues; // In-Out: attr values 

P_FS_ATTR_SIZE pAttrSizes; // In-Out: attr sizes 

} FS GET SET ATTR, * P FS GET SET ATTR; 
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Cottiments Specify which attributes you wish to set via an array of attribute labels pointed to by pAttrLabels. The 

number of attribute labels is specified by numAttrs. The values are specified via an array of values. If the 
nth value represents a string or variable attribute supply the pointer to the string/variable. If the nth 
value represents a Fix64 attribute two consecutive U32 values are expected. If there are no variable length 
attributes, pAttrSizes can be set to pNuIl, because the size of Fix32, Fix64 and string attributes can be 
inferred. 

pAttrLabels, pAttrValues & pAttrSizes are inputs only for this message. The parm pPath is relative to 
the object that receives this message. 

The attr fsAttrDirlndex (dir indexes) can be set on directories to establish an alternate access to a 
directory without having to specify the path to the directory. See msgNew above on how to access 
directories with a dir index. Only directories that reside under the PenPoint tree (any directories below 
the PenPoint directory on a given volume) can have dir index attributes. If another directory already has 
the same dir index as the one given then a stsFSDirlndexExists error is returned. 

NOTE: Most attributes (with the exception of dir index and old dir index attributes) can be stored with 
either files or directories. The root of a volume is the exception. No attributes may be stored with the 
root. 

ieturn ¥oloe stsFSBadPath New name for name attr is invalid. 

stsFSNotDir Dir index attr cannot be set on a file. 

stsFSReadOnlyAttr File size cannot be set via set attr, use msgPSSetSize. 

msgFSMove 

Moves a node (and any children) to a new destination. 

Takes P_FS_MOVE_COPY, returns STATUS. 

#define msgFSMove MakeMsg(clsFileSysteiii, 29) 

Argymenfs typedef Struct FS_MOVE_COPY { 

P_STRING pSourcePath; // path of source of move or copy 

FS_LOCATOR destLocator; // locator to destination node 

FS_MOVE_COPY_MODE mode; // options that affect move or copy 

FS_MOVE_COPY_EXIST exist; // action to take if exists or doesn't 

P_STRING pNewDestName; // Out: See comment above 

BOOLEAN alreadyExisted; // Out: indicates if already exists 

U32 spare; 

} FS_MOVE_COPY, * P_FS_MOVE_COPY; 

Comments The destination file/dir name of a move is derived as follows. 

For "fsMoveCopyToDest" (the default): If non null path is provided then dest name is the leaf name of 
the path and the path up to the leaf name determines the destination directory. If the path is null then 
the name of the destination object is used as the dest name and the parent of the destination object is 
used as the destination directory. 

For fsMoveCopylntoDest: The entire destination uid and path are used for the destination directory. 
And the destination name is taken from the source name. 

The parm pSourcePath is relative to the object that receives this message. 

NOTE: pNewDestName is not an in parameter. It is an output parameter that gives the (new, if 
fsMoveCopyGenUnique was specified for exist) name of the copied node. Set pNewDestName to a 
buffer if you want to know the name, set pNewDestName to pNidl if you do not. 
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ri Voiue stsFSBadPath Path or parts of path are too large. 

stsFSCircularMoveCopy Occurs when copying dir to an ancestor (parent). S 

Jso msgFSMoveNotify, msgFSCopy 



msgFSCopy 

Copies a node (and any children) to a new destination 
Takes P_FS_MOVE_COPY, returns STATUS. 
♦define msgFSCopy 



MakeMsg(clsFileSystem, 30) 



typedef struct FS MOVE COPY { 



P_STRING 

FS_LOCATOR 

FS_MOVE_COPY_MODE 

FS MOVE COPY EXIST exist; 



pSourcePath; // path of source of move or copy 

destLocator; // locator to destination node 

mode; // options that affect move or copy 

_ _ _ // action to take if exists or doesn't 

P_STRING pNewDestName; // Out: See comment above 

BOOLEAN alreadyExisted; // Out: indicates if already exists 

U32 spare; 

} FS_MOVE_COPY, * P_FS_MOVE_COPY; 

The destination file/dir of a copy is derived as follows. 

For "fsMoveCopyTo" (the default): If non null path is provided then dest name is the leaf name of the 
path and the path up to the leaf name determines the destination directory. If the path is null then the 
name of the destination object is used as the dest name and the parent of the destination object is used 
as the destination directory. 

For fsMoveCopylnto: The entire destination uid and path are used for the destination directory. And 
the destination name is taken from the source name. 

The parm pSourcePath is relative to the object that receives this message. 

NOTE: pNewDestName is not an in parameter. It is an output parameter that gives the (new, if 
fsMoveCopyGenUnique was specified for exist) name of the copied node. Set pNewDestName to a 
buffer if you want to know the name, set pNewDestName to pNull if you do not. 

StsFSBadPath Path or parts of path are too large. 

StsFSCircularMoveCopy Occurs when copying dir to an ancestor (parent). 

msgFSCopyNotify, msgFSMove 



msgFSMoveNotify 

Same as msgFSMove with notification routine extensions. 
Takes P_FS_MOVE_COPY_NOTIFY, returns STATUS. 

#define msgFSMoveNotify MakeMsg(clsFileSystem, 70) 

// the time that the current event occurred 



Enumie ( FS_NOTIFY_TIME ) { 
fsBeginOperation = 1, 
fsBeforeOperation = 2, 
fsDuringOperation = 3, 
fsAfterOperation = 4, 
fsEndOperation = 5 

}; 



// beginning of whole operation 

// before the sub operation 

// during the sub operation 

// after the sub operation 

// end of the whole operation 
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read operation 
write operation 
create operation 
// verify operation 
// delete operation 
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// the operation of the current event 
Enumie { FS_NOTIFY_OP ) { 

fsReadOperation =1, // 

fsWriteOperation =2, // 

fsCreateOperation =3, // 

fsVerifyOperation = 4, 
fsDeleteOperation = 5 
}; 

// information required by the notification routine 
typedef struct FS_NOTIFY_RTN_INFO { 

a handle to the current file 
if move operation 
if source is a directory 
attributes for current file 
time context of notification 
// op context of notification 
// max size of operation buffer 
actual size of operation 
actual size of file 
spare: unused 
spare : unused 
} FS_NOTIFY_RTN_INFO, *P_FS_NOTIFY_RTN_INFO; 
// the definition of the notification routine 

typedef STATUS FunctionPtr ( P_FS_NOTIFY_RTN ) ( P_FS_NOTIFY_RTN_INFO pFSNotifyRtnlnfo, 

P_UNKNOWN pClientData ) ; 

// the information required for FSMove/CopyNotify 
typedef struct FS_MOVE_COPY_NOTIFY { 

P_STRING 

FS_LOCATOR 

FS_MOVE_COPY_MODE 

FS_MOVE_COP Y_EXI ST 

P_STRING 

BOOLEAN 

P_UNKNOWN 

P_UNKNOWN 

P_UNKNOWN 

U32 

U32 
} FS MOVE COPY NOTIFY, 



OBJECT 


source; 


// 


BOOLEAN 


moveOperation; 


// 


BOOLEAN 


isADirectory; 


// 


P FS GET SET ATTR 


pFSGetSetAttr; 


// 


FS_NOTIFY TIME 


fsNotifyTime; 


// 


FS NOTIFY OP 


fsNotifyOp; 


// 


U32 


bufferSize; 


// 


U32 


operationSize; 


// 


U32 


fileSize; 


// 


U32 


sparel; 


// 


U32 


spa re 2; 


// 



pSourcePath; 

destLocator; 

mode; 

exist; 

pNewD est Name; 

alreadyExisted; 

pNotifyRtn; 

pClientData; 

pQuickSortRtn; 

sparel; 

spare2 ; 



// path of source of move or copy 

// locator to destination node 

// options that affect move or copy 

// action to take if exists or doesn't 

// Out: See comment w/msgFSMove 

// Out: indicates if already exists 

// notification routine 

client data to notification routine 

quicksort routine 

spare: unused 

spare: unused 



// 
// 
// 
// 



* P FS MOVE COPY NOTIFY; 



srwments 



The parm pSourcePath is relative to tlie object that receives this message. 



tessage 



msgFSCopyNotify 

Same as msgFSCopy w^ith notification routine extensions. 

Takes P_FS_MOVE_COPY_NOTIFY, returns STATUS. 

#define msgFSCopyNotify MakeMsg(clsFileSystem, 71) 



typedef struct FS_MOVE 

P_STRING 

FS_LOCATOR 

FS_MOVE_COPY_MODE 

FS_MOVE_COPY_EXIST 

P_STRING 

BOOLEAN 

P_UNKNOWN 

P_UNKNOWN 

P_UNKNOWN 

U32 

U32 
} FS MOVE COPY NOTIFY, 



COPY_NOTIFY { 

pSourcePath; 

destLocator; 

mode ; 

exist; 

pNewDestName; 

alreadyExisted; 

pNotifyRtn; 

pClientData; 

pQuickSortRtn; 

sparel; 

spare2 ; 
* P FS MOVE COPY 



// path of source of move or copy 

// locator to destination node 

// options that affect move or copy 

// action to take if exists or doesn't 

// Out: See comment w/msgFSMove 

// Out: indicates if already exists 

// notification routine 

// client data to notification routine 

// quicksort routine 



// 
// 
NOTIFY; 



spare : 
spare ; 



unused 
unused 



The parm pSourcePath is relative to the object that receives this message. 
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msgFSDelete 

Deletes a node (and all of its children). 

Takes P_STRING, returns STATUS. 

#define msgFSDelete MakeMsg(clsFileSystem, 31) 

Comments The object of msgFSDelete is typically a dir handle, but it can also be a file handle, but the argument 

passed must be set to pNull. Afi:er a node is deleted, its handle is marked corrupt (since it is no longer 
valid). A dir handle object can be reused via msgFSSetTarget or destroyed via msgDestroy. A file handle 
must be destroyed aft:er the node is deleted. The argument (a path) is relative to the object that receives 
this message. 

Return Valye stsFSVolDisconnected The volume is not connected. 

stsFSVolReadOnly A node cannot be deleted, because the volume is write protected. 

stsFSNodeReadOnly Node cannot be deleted because the read only flag is set on the node. 

stsFSNodeBusy Node cannot be deleted because it is being access by another client. 
See Also msgFSForceDelete 



msgFSFlush 

Flushes any buffers and attributes associated with the file or directory. 

Takes void, returns STATUS. 

♦define msgFSFlush MakeMsg(clsFileHandle, 20) 

Commeots This can be used to guarantee that cached buffers are flushed to the disk and can also be used to flush 

memory mapped files to disk. 

msgFSMakeNative 

Removes anything not supported by the native file system. 

Takes P_FS_MAKE_NATIVE, returns STATUS. 

♦define msgFSMakeNative MakeMsg(clsFileSystem, 32) 

Arguments typedef Struct FS_MAKE_NATIVE { 

P_STRING pPath; // path to node to make native 

P_STRING pNewName; // Out: native name if changed 

} FS_MAKE_NATIVE, * P_FS_MAKE_NATIVE; 

Comments The parm pPath is relative to the object that receives this message. 

msgFSEjectMedia 

Ejects media firom an ejectable, removable volume. 
Takes void, returns STATUS. 

tdefine msgFSEjectMedia MakeMsg(clsFileSystem, 34) 

Return ¥oiye stsOK The volume media has been ejected. 

StsFSVolDisconnected The volume media is already ejected. 
stsRequestNotSupported The volume does not have ejectable media 
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msgFSForceDelete 

Forcibly deletes a node (and all of its childen). 

Takes P_STRING, returns STATUS. 

♦define msgFSForceDelete MakeMsg(clsFileSystem, 35) 

roinmenfs WARNING. Normal restrictions do not apply. The node will still be deleted even if it is being accessed 

via another handle or if it is marked read only. However, if the volume is not connected or is write 
protected, the forced delete will still fail. 

After a node is deleted, its handle is marked corrupt (since it is no longer valid). A dir handle object can 
be reused via msgFSSetTarget or destroyed via msgDestroy. A file handle must be destroyed after the 
node is deleted. The argument (a path) is relative to the object that receives this message. 

iee Ais© msgFSDelete 



msgFSVolSpecific 

Sends a volume specific message via a dir or file handle. 

Takes P_FS_VOL_SPECIFIC, returns STATUS. . 

tdefine msgFSVolSpecific MakeMsg{clsFileSystem, 40) 

Argymenfs typedef Struct FS_VOL_SPECIFIC { 

P_STRING pPath; // path of node to receive msg 

MESSAGE msg; // message to pass on to volume 

P_UNKNOWN pArgs; // In-Out : message specific args 

} FS_VOL_SPECIFIC, * P_FS_VOL_SPECIFIC; 

ieturn ¥oltje Volume specific errors. 

msgPSChanged 

Notifies observers of directory changes. 

Takes P_FS_CHANGE_INFO, returns STATUS. Category: observer notification. 

tdefine msgFSChanged MakeMsg(clsFileSystem, 50) 

Arguments typedef Struct FS_CHANGE_INFO { 

MESSAGE reason; // fs message that caused the change 

OBJECT observed; // observed dir whose content changed 

U32 sparel; 

U32 spare2; 

} FS_CHANGE_INFO, * P_FS_CHANGE_INFO; 

These messages are the reason observers of a dir handle would be notified of a change and the 
circumstances that the change happens: 

msglnit A file or dir has been created. 

msgFree A temp file or temp directory has been deleted. 

msgFSDelete A file or directory has been deleted. 

msgFSForceDelete A file or directory has been deleted. 

msgFSMove A file or directory has been "fast" moved. 

Comments This notifies observers of directories (not files) when a file or dir within the directory changes. The 

change reasons described below are changes to the directory or file node, not the handle referencing the 
node. 
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msgFSVolChanged 

Notifies observer of volume changes. 

Takes P_FS_VOL_CHANGE_INFO, returns STATUS. Category: observer notification. 

#define msgFSVolChanged MakeMsg(clsFileSystem, 51) 

lumenfs Enuml6 (FS_VOL_CHANGE_FLAGS) { 

fsVolChangeWhilePrompting = flagO // FS prompting caused change 

}; 

typedef struct FS_VOL_CHANGE_INFO { 

MESSAGE reason; // fs message that caused the change 

OBJECT rootDir; // root dh of volume that changed 

FS_VOL_CHANGE_FLAGS flags; // more info related to reason 
U16 sparel; 

U32 spare2; 

} FS_VOL_CHANGE_INFO, * P_FS_VOL_CHANGE_INFO; 

These messages are the reason observers of theFileSystem would be notified of a volume addition, 
removal or change of state. Note: msgFSSetVolName (defined above) is also a volume change reason. 

tdefine msgFSInstallVol MakeMsg(clsFileSystem, 1) 

tdefine msgFSRemoveVol MakeMsg (clsFileSystem, 2) 

tdefine msgFSConnectVol MakeMsg (clsFileSystem, 3) 

tdefine msgFSDisconnectVol MakeMsg (clsFileSystem, 4) 

Observe the well known object, theFileSystem, if you want to receive this. 



Class DirHandle Messages 



msgFSSetTarget 

Changes the target directory to directory specified by locator. 

Takes P_FS_LOCATOR, returns STATUS. 

tdefine msgFSSetTarget MakeMsg (clsDirHandle, 20) 

typedef struct FS_LOCATOR { 

OBJECT uid; 

P_STRING pPath; // Relative to node defined by uid 

} FS_LOCATOR, * P_FS_LOCATOR; 

Setting a dir handle object to a new target also resets the read dir pointer. 

stsFSUnchangeable The recipient of this message has been "opened" with the fsUnchangeable flag set 
in pNew->mode. 



msgFSReadDir 

Reads the next entry (its attributes) from a directory. 

Takes P_FS_READ_DIR, returns STATUS. 

tdefine msgFSReadDir MakeMsg (clsDirHandle, 21) 

Arsum€»nts typedef struct FS_READ_DIR { 

struct FS_READ_DIR * pNext; // Out: only used w/msgFSReadDirFull 

U16 numAttrs; // In-Out: attrs of interest 

P_FS_ATTR_LABEL pAttrLabels; // In-Out: ptr to attr labels 

P_UNKNOWN pAtt rvalues; // In-Out: ptr to attr values 

P_FS_ATTR_SIZE pAttrSizes; // In-Out: ptr to attr sizes 

} FS READ DIR, * P FS READ DIR; 
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Specify which attributes you wish returned via an array of attribute labels pointed to by pAttrLabels. 
The number of attribute labels is specified by numAttrs. See msgFSGetAttr for a description on setting 
pAttrValues and pAttrSizes. 



msgFSReadDirReset 

Resets the ReadDir position to the beginning. 

Takes void, returns STATUS. 

#define msgFSReadDirReset MakeMsg(clsDirHandle, 22) 

Comments This will direct msgFSReadDir to begin reading from the first entry in the directory. This has no effect 

on msgFSReadDirFull, The default after creating a handle to a directory is to point to the first entry. 



msgFSReadDirFull 

Reads all the entries in a directory into a local buffer. 

Takes P_FS_READ_DIR_FULL, returns STATUS. 

#define msgFSReadDirFull MakeMsg(clsDirHandle, 23) 

Argymenfs typedef struct FS_READ_DIR_FULL { 

U16 numAttrs; // num of labels in label array 

P_FS_ATTR_LABEL pAttrLabels; // attrs of interest to be read 

U32 numEntries; // Out: number of dir entries 

U32 bufLength; // Out: length of pDirBuf 

P_FS_READ_DIR pDirBuf; // Out: points to first entry 

} FS_READ_DIR_FULL, * P_FS_READ_DIR_FULL; 

Comments Specify which attributes you wish returned via an array of attribute labels pointed to by pAttrLabels. 

The number of attribute labels is specified by numAttrs. 

The returned data is a linked list of FS_READ_DIR entries, linked by the pNext field. The last link is 
specified by a pLink == pNull. 

The client must free the returned buffer pDirBuf, using OSHeapBlockFree. The buffer should not be 
freed if it has a value of pNulI, which will be the case if there are any errors or if numEntries is zero. 



msgFSTraverse 

Traverse through the nodes of a tree starting with the target of this msg. 

Takes P_FS_TRAVERSE, returns STATUS. 

♦define msgFSTraverse MakeMsg(clsDirHandle, 24) 

Faricfion Prototype typedef STATUS FunctionPtr (P_FS_TRAVERSE_CALL_BACK) ( 

OBJECT dir, // dir handle to current node 

U16 level, // level in the hierarchy 

P_FS_READ_DIR pNextEntry, // info about next entry 

P_UNKNOWN pClientData // the client's data 

); 

typedef struct FS_TRAVERSE { 

FS_TRAVERSE_MODE mode; // call back order and criteria 

U16 numAttrs; // num of labels in label array 

P_FS_ATTR_LABEL pAttrLabels; // attr label array 

P_FS_TRAVERSE_CALL_BACK pCallBackRtn; // called for each dir & file 

P_UNKNOWN pClientData; // passed to call back routine 

P_UNKNOWN pQuickSortRtn; // optional quick sort routine 

} FS TRAVERSE, * P FS TRAVERSE; 
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ts This message traverses the file system tree beginning with the directory which is the recipient of this 

message and traverses the node tree depth first. The client will be called back via pCallBackRtn at each 
node depending on mode (see FS_TRAVERSE_MODE above). Optionally, the nodes at each directory level ^ 

can be sorted before being returned by specifying a quick sort routine via pQuickSortRtn (See quicksort «« 

in sort.h). 

Specify which attributes you wish returned via an array of attribute labels pointed to by pAttrLabels. 
The number of attribute labels is specified by numAttrs. At a minimum, pAttrLabels must contain 
fsAttrName and fsAttrFlags. 

Retyrn Voioe stsBadParam Did not specify fsAttrName/fsAttrFlags in labels. 

stsFSUnchangeable The recipient of this message has been "opened" with the fsUnchangeable flag set 
in pNew->mode. This is a common error if trying to traverse from the root dir (which is 
unchangeable) provided by msgFSGetlnstalledVolumes/msgFSGetVolMetrics. Create a handle to 
the root and use that to traverse instead. 



stsFSNestingTooDeep Dir tree is deeper than fsMaxNestingLevel levels. 
Prototype for the call back routine used by msgFSTraverseTree 

Class FileHandle Messages 



msgStreamRead 

Reads data from the file. 

Takes P_STREAM_READ_WRITE, returns STATUS. Category: descendant responsibility. 
Comments The maximum number of bytes read with a single request is determined by fsMaxReadWrite. 

teturnVaiye stsBadParam Requesting more than fsMaxReadWrite bytes. 

See Also msgStreamRcad in stream. h 

msgStreamWrite 

Writes data to the file. 

Takes P_STREAM_READ_WRITE, returns STATUS. Category: descendant responsibility. 

Comments The maximum number of bytes writable with a single request is determined by fsMaxReadWrite. Note 

that writes to a memory mapped file that cause the file to grow will result in a stsFSNodeBusy error. 
Free the memory map file pointer before growing the file. 

Retyrn Value StsBadParam Requesting more than fsMaxReadWrite bytes. 

stsFSNodeReadOnly This is a read only file. 

stsFSVolFull The file could not be written - no space on volume. 

StsFSNodeBusy The file is memory mapped and this write request would cause the file to be grown 
beyond the memory mapped size. 

See Mso msgStreamWrite in stream.h 
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styrn ¥alye 



msgStreamFlush 

Flushes any buflFers associated with the file. 

Takes void, returns STATUS. Category: descendant responsibility. 

msgStreamFlush in stream.h 

msgStreamSeek 

Seeks to new position within the file. 

Takes P_STREAM_SEEK, returns STATUS. Category: descendant responsibility. 

stsBadParam Seek mode is out of range. 

msgStreamSeek in stream.h 

msgFSSeek 

Sets the value of the current byte position. 
Takes P_FS_SEEK, returns STATUS. 
#define msgFSSeek 

typedef struct FS_SEEK { 

FS_SEEK_MODE mode; 

S32 offset; 

U32 curPos; 

U32 oldPos; 

BOOLEAN eof; 
} FS_SEEK, * P_FS_SEEK; 

StsBadParam Seek mode is out of range. 



MakeMsg(clsFileHandle, 21) 



// seek from bof, cur pos, eof 
// relative change from seek origin 
// Out: cur byte pos after seek 
// Out: cur byte pos before seek 
// Out: Is new pos at end of file? 



msgFSGetSize 

Gets the size of the file. 

Takes P_FS_FILE_SIZE, returns STATUS. 

#define msgFSGetSize 



MakeMsg(clsFileHandle, 22) 



msgFSSetSize 

Sets the size of the file. 

Takes P_FS_SET_SIZE, returns STATUS. 

tdefine msgFSSetSize 

typedef struct FS_SET_SIZE { 

FS_FILE_SIZE newSize; 

FS_FILE_SIZE oldSize; 

} FS SET SIZE, * P FS SET SIZE; 



MakeMsg(clsFileHandle, 23) 

// new file size 

// Out: prior file size 



Note that a set size to a memory mapped file that causes the file to grow will result in a stsFSNodeBusy 
error. Free the memory map file pointer before growing the file. 

stsFSNodeReadOnly This is a read only file. 

stsFSVolFull The file could not be grown - no space on volume. 

StsFSNodeBusy The file is memory mapped and this set size request would cause the file to be grown 
beyond the memory mapped size. 
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msgFSMemoiyMap 

Associates the file with a directly accessible memory pointer. 

>- 
Takes PP_MEM, returns STATUS. "^ 

tdefine msgFSMemoryMap MakeMsg{clsFileHandle, 24) 

To get a memory mapped file pointer fi-om shared memory, the file handle must be created with 
pNew->fs.mode 1= fsSharedMemoryMap. 

msgFSMemoiyMapFree 

Frees the memory map pointer currently associated with the file. 
Takes void, returns STATUS. 

♦define itisgFSMemoryMapFree MakeMsg(clsFileHandle, 25) 

Comments NOTE: Memory map pointers are fi-eed for you at msgFree of a file handle. 

msgFSMemoiyMapSetSize 

Sets the size of the file's memory map. 

Takes SIZEOF, returns STATUS. 

tdefine msgFSMemoryMapSetSize MakeMsg(clsFileHandle, 26) 

Comments Determines the limit of a memory map for the file. The size can't be less than the file size, nor less than a 

limit set by another client but can be larger. The memory map size must be set before memory mapping 
the file. 

Uefum ¥al«e stsFSNodeBusy The file is currently memory mapped. 

msgFSMemoiyMapGetSize 

Gets the size of the file's memory map. 

Takes P_SIZEOF, returns STATUS. 

tdefine msgFSMemoryMapGetSize MakeMsg(clsFileHandle, 27) 



Public Functions 



FSNameValid 

Checks a file/dir name for validity. 

Returns STATUS. 

¥umtmn Prototype STATUS EXPORTED FSNameValid ( 

P_STRING pName // name of file/dir to validate 

); 

Retwrn Voiue stsOK The node name is valid. 

stsFailed The node name was invalid. 

Name is bad if it has no characters, is greater than 32 characters, has leading or trailing spaces, contains 
the pathname delimeter char, contains the file system escape character, or is the name of self (.) or parent 
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FSUTIL.H 



This file contains filesystem attribute helper procedures. The functions described in this file are 
contained in SYSUTIL.LIB. 

These procedures make it easier to deal with filesystem attributes. They also support list attributes; 
variable attributes which maintains lists of 4-byte quanitities. 

tifndef FSUTIL_INCLUDED 
#define FSUTIL_INCLUDED 

#ifndef FS_INCLUDED 
tinclude <fs.h> 
#endif 



Fiinction Protot^ 



GetNodeName 

Gets the name attribute of a given filesystem node. 
Returns STATUS. 



STATUS EXPORTED GetNodeName ( 

OBJECT handle, 

P_STRING pName) ; 



// File or dir handle. 
// Out: name. 



Use this fiinction to easily get the name of a node. 



GetAttr 

Gets a single FIX32 attribute from a filesystem handle. 
Returns STATUS. 



STATUS EXPORTED GetAttr ( 

FS_ATTR_LABEL attrLabel, 

OBJECT handle, 

P U32 pValue) ; 



// Attribute label. 
// File or dir handle. 
// Out: attribute value. 



This is only for FIX32 attributes when you have a handle onto the node; see GetSingleAttr for a more 
general fijnction. 



GetSingleAttr 

Gets a single FIX32, FIX64, or known-size STRING attribute. 
Returns STATUS. 



Fynstion Prototype STATUS EXPORTED GetSingleAttr ( 



FS ATTR LABEL 


attrLabel, 


// 


In: 


Attribute label. 


OBJECT 


handle. 


// 


In: 


handle of node. 


P STRING 


pPath, 


// 


In: 


path of node. 


P UNKNOWN 


pValue) ; 


// 


Out 


: attribute value 
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SetAttr 

Sets a single FIX32 attribute on a filesystem handle. 
Returns STATUS. 



STATUS EXPORTED SetAttr ( 

FS_ATTR_LABEL attrLabel, 

OBJECT handle, 

U32 value) ; 



// Attribute label. 
// File or dir handle. 
// Attribute value. 



This is only for FIX32 attributes when you have a handle onto the node; see SetSingleAttr for a more 
general function. 



Fiifictiosi Pr< 



SetSingleAttr 

Sets a single FIX32, FIX64, or STRING attribute. 
Returns STATUS. 



STATUS EXPORTED SetSingleAttr ( 

FS_ATTR_LABEL attrLabel, 

OBJECT handle, 

P_STRING pPath, 

P_UNKNOWN pValue) ; 



// In: Attribute label. 

// In: handle of node. 

// In: path of node. 

// In: attribute value. 



GetListX 

Gets a VAR attribute that is organized as a list of values. 

Returns STATUS. 

) GetListX ( 

// File or dir handle. 

// Path relative to handle. 

// Attribute label. 

// Out: list. 

// Out: size (in bytes) of list. 

Allocates ppList from the process local stack. Caller must HeapBlockFree ppList when done adding 
removing, and putting the list. 



STATUS EXPORTED GetListX ( 




OBJECT 


handle. 


P_STRING 


pPath, 


FS_ATTR_LABEL 


attrLabel, 


PP UNKNOWN 


ppList, 


P U16 


pSize) ; 



tion Prototype 



PutListX 




Updates a list attribute with ; 


1 new list. 


Returns STATUS. 




STATUS EXPORTED PutListX ( 




OBJECT 


handle. 


P_STRING 


pPath, 


FS_ATTR_LABEL 


attrLabel, 


P UNKNOWN 


pList, 


U16 


size) ; 



// File or dir handle. 

// Path relative to handle. 

// Attribute label. 

// List. 

// Size (in bytes) of list. 



FSUTIL.H 
Private 
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FindListltemX 

Finds an element in a list. 

Returns STATUS. 

Function Prototype STATUS EXPORTED FindListltemX ( 

P_UNICNOWN pltem, 

U16 itemSize, 

P_UNKNOWN pList, 

U16 listSize, 

P U16 pOffset); 



Comments 



Refyrn ¥alye 



// Data to search for. 

// Size of data to search for. 

// List. 

// Size of list. 

// Out: offset of found item. 



The list must first be gotten via GetList. pOfFset is based. The Ust array can be indexed with pOfFset 
to get the actual data. The comparison is done via a memcmp, so things must be EXACTLY the same. 

stsNoMatch Item not found. 



AddListltetnX 

Adds an item to the end of a list. 

Returns STATUS. 

Function Prototype STATUS EXPORTED AddListItemX( 

P_UNKNOWN pltem, 

U16 itemSize, 

PP_UNKNOWN ppList, 

P_U16 pSize) ; 



// Item to add. 

// Size of item in bytes. 

// In .-Out List. 

// In: Out size of list in bytes, 



Communis The list must first be gotten via GetList. The heap that the list uses is resized. pSize is updated to reflect 

the new list size. 



Function Fratatype 



Comttients 



RemoveListltemX 

Removes an item from a list, given an offset. 

Returns STATUS. 

STATUS EXPORTED RemoveListltemX ( 
U16 offset, 

U16 size, 

PP_UNKNOWN ppList, 

P_U16 pSize) ; 



// Offset of item to remove, 

// Size of item to remove. 

// In: Out List. 

// In:Out Size of list. 



The list must first be gotten via GetList. The heap that the list uses is resized. If pSize == 1 (only 1 item 
left) then *pSize is set to 0, but the list heap is not resized, offset is 0-based. 



Private 



Below are the "old" attribute list functions. These are here for backwards compatability only! 



GetList 

Gets a VAR attribute that is organized as a list of 4 byte values. 
Returns STATUS. 



FunctioR Prototype 


STATUS EXPORTED GetList ( 






OBJECT 


handle. 




P STRING 


pPath, 




FS ATTR LABEL 


attrLabel, 




PP OBJECT 


ppList, 




P U16 


pCount) ; 



// File or dir handle. 

// Path relative to handle, 

// Attribute label. 

// Out: list. 

// Out: number of elements, 
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Allocates ppList from the process local stack. Caller must HeapBlockFree ppList when done adding, 
removing, and putting the list. 



PutList 

Updates a list attribute with a new list. 
Returns STATUS. 



STATUS EXPORTED PutList ( 




OBJECT 


handle, 


P_STRING 


pPath, . 


FS_ATTR_LABEL 


attrLabel, 


P OBJECT 


pList, 


U16 


count) ; 



// File or dir handle. 

// Path relative to handle, 

// Attribute label. 

// List. 

// Number of elements. 



FindListltem 

Finds an element in a list. 

Returns STATUS. 

STATUS EXPORTED FindListltem ( 

OBJECT item, 

P_OBJECT pList, 

U16 count, 

P U16 pindex); 



// Data to search for. 

// List. 

// Number of elements in list, 

// Out: index of found item. 



The list must first be gotten via GetList. pindex is based. The list array can be indexed with pindex to 
get the actual data. 

stsNoMatch Item not found. 



rURcfi€>n rn 
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AddListltem 

Adds an item to the end of a list. 

Returns STATUS. 

STATUS EXPORTED AddListltem ( 

OBJECT item, 

PP_OBJECT ppList, 

P U16 pCount) ; 



// Item to add. 
// In: Out List. 
// In: Out number of elements in list, 



The list must first be gotten via GetList. The heap that the list uses is resized. pCount is updated to 
reflect the new list size. 



Fyncfion Prototype 



RemoveListltem 

Removes an item from a list, given an index. 

Returns STATUS. 

STATUS EXPORTED RemoveListltem ( 
U16 index, 

PP_OBJECT ppList, 

P U16 pCount); 



// Index of item to remove. 

// In: Out List. 

// In: Out Number of elements in list. 



The list must first be gotten via GetList. The heap that the list uses is resized. If pCount == 1 (only 1 
item left:) then *pCount is set to 0, but the list heap is not resized, index is 0-based. 
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STREAM.H 



This file contains the API definition for clsStream. 

clsStream inherits from clsObject. 

clsStream is an abstract class - it does not completely implement its own protocol. Subclasses of 

clsStream must complete the implementation. clsFileHandle is an important subclass of clsStream (see 

fs.h). 

The functions described in this file are contained in PENPOINT.LIB. 

#ifndef STREAM_INCLUDED 
tdefine STREAM_INCLUDED 

tifndef GO_INCLUDED 

tinclude <go.h> 

tendif 

tifndef UID_INCLUDED 

#include <uid.h> 

tendif 

#ifndef OSTYPES_INCLUDED 

tinclude <ostypes.h> 

tendif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

Common #defines and typedefs 

tdefine streamNewFields \ 

objectNewFields 
typedef struct STREAM_NEW { 

StreamNewFields 
} STREAM_NEW, * P_STREAM_NEW; 

Several types in this file contain "streamElements." 
The StreamElements fields are: 

♦ numBytes: In: size of buffer 

♦ pBuf: In: buffer 

♦ count: Out: number of bytes transferred 

tdefine streamElements \ 

U32 numBytes; \ 

P_UNKNOWN pBuf; \ 
U32 count; 

Status codes 

tdefine stsTimeOutWithData MakeWarning (clsStream, 1) 

stsStreamDisconnected status is returned by all stream calls when the service executing the stream 

function is no longer in a connected state (A disconnectable service is clsMILAsyncSIO). 

Clients must not send other stream messages to the disconnected service. 
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Penpoint can notify clients or clients may find services' connected states (see service.h and servmgr.h). 
#define stsStreamDisconnected MakeStatus (clsStream, 1) 



Messages 



msgStreamRead 

Reads data firom stream. 

Takes P_STREAM_READ_WRITE, returns STATUS. Category: descendant responsibility. 

♦define msgStreamRead MakeMsg (clsStream, 1) 

Argument's typedef Struct { 

streamElements 
} STREAM_READ_WRITE, * P_STREAM_READ_WRITE; 

Comments msgStrcamRcad reads data from the stream into pBuf. pBuf must point to a buffer which can hold at 

least numBytes bytes. The number of bytes read is passed back in count. 

If you try to read bytes when at the end of the data stream stsOK is returned. 

Return Value < stsOK No data read. 

>= StsOK Count of bytes is non-zero. 

stsEndOfData Count is zero and at the end of data. 



msgStreamWrite 

Writes data to stream. 

Takes P_STREAM_READ_WRITE, returns STATUS. Category: descendant responsibility. 

#define msgStreamWrite MakeMsg (clsStream, 2) 

Message typedef Struct { 

Arguments StreamElements 

} STREAM_READ_WRITE, * P_STREAM_READ_WRITE; 

Comments Writes numBytes from pBuf into the stream. Returns stsOK if all bytes are written. 

msgStreamReadTimeOut 

Reads data from stream with timeout. 

Takes P_STREAM_READ_WRITE_TIMEOUT, returns STATUS. Category: descendant responsibility. 

♦define msgStreamReadTimeOut MakeMsg (clsStream, 3) 

Argumenfs typedef Struct { 

StreamElements 

OS_MILLISECONDS timeOut; // In: milliseconds until timeout 

} STREAM_READ_WRITE_TIMEOUT, * P_STREAM_READ_WRITE_TIMEOUT; 

Comments msgStreamReadTimeOut reads data from the stream into pBuf. pBuf must point to a buffer which can 

hold least numBytes bytes. The number of bytes read is passed back in count. 

When count is greater than zero the status returned is always greater than or equal to stsOK. 

ietym ¥alue stsTimeOutWithData Count is greater than zero but less than numBytes because of a timeout. 

stsTimeOut Count is zero and the timeout has expired. 

StsEndOfData Count is zero and at the end of data. 
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msgStreamWriteTimeOut 

Writes to the stream with timeout. 

Takes P_STREAM_READ_WRITE_TIMEOUT, returns STATUS. Category: descendant responsibiHty. 

#define msgStreamWriteTimeOut MakeMsg{clsStream, 4) 

Mess&ge typedef struct { 

Argymenfs streamElements 

OS_MILLI SECONDS timeOut; // In: milliseconds until timeout 

} STREAM_READ_WRITE_TIMEOUT, * P_STREAM_READ_WRITE_TIiyiEOUT; 

Comments Writes numBytes from pBuf into the stream. 

tetyrn Value stsOK All bytes were written. 

stsTimeOut Timeout has expired before all data written. 

msgStreamFlush 

The stream flushes any buffered data. 

Takes pNuU, returns STATUS. Category: descendant responsibility. 

#define msgStreamFlush MakeMsg(clsStream, 5) 

Comments clsStream's default response is to return stsMessagelgnored. Most subclasses override clsStream's 

response. 

Retorn Voiue stsOK Buffers were successfully emptied. 

stsFailed Buffers do not empty after some timeout period. 

msgStreamSeek 

Sets the stream's Current Byte Position. 

Takes P_STREAM_SEEK, returns STATUS. 

#define msgStreamSeek MakeMsg(clsStream, 6) 

? Enuml6(STREAM_SEEK_M0DE) { 

// Relative to beginning of file, end of file, or Current Byte Position 
streamSeekBeginning = 0, 

streamSeekEnd = 1, 

streamSeekCurrent = 2, 

// Default setting 

streamSeekDefaultMode = streamSeekBeginning 
}; 



typedef struct STREAM_SEEK { 

STREAM_SEEK_MODE mode; // 

S32 offset 

U32 curPos 

U32 oldPos 



// relative change from seek origin 
// Out: byte position after seek 
// Out: byte position before seek 



BOOLEAN eof; // Out: Is new pos at end of file? 

} STREAM_SEEK, * P_STREAM_SEEK; 

Commefifs clsStxeam's default response is to return stsMessagelgnored. Most subclasses override clsStream's 

response. 
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msgStreamBlockSize 

Passes back the most efficient write block size for this stream. 

Takes P_STREAM_BLOCK_SIZE, returns STATUS. Category: descendant responsibility. 

fdefine msgStreamBlockSize MakeMsg(clsStream,7) 

Quments typedef struct { 

U32 blockSize; // out: preferred write block size 

} STREAM_BLOCK_SIZE, * P_STREAM_BLOCK_SIZE; 

tiinieiifs clsStream's default response is to return a blockSize of 512. Most subclasses override clsStream's 

response. 

Functions 

The P_UNKNOWN declarations for the following are assumed to be FILE*. Maintaining a clean 
separation between ANSI and PenPoint header files prevents the use of the true type. 

StdioStreamBind 

Returns a stdio file pointer bound to a stream object. 

Returns pointer to FILE. 

rpe P_UNKNOWN EXPORTED StdioStreamBind ( 
OBJECT obj); 



StdioStreamUnbind 

Frees the stdio file handle bound to a stream object. 

Returns int. 

funxflon Prefofype int EXPORTED StdioStreamUnbind ( 
P_UNKNOWN pFile) ; 

StdioStreamToObject 

Returns the stream object bound to a stdio file pointer. 

Returns OBJECT. 

FoBcfion Prototype OBJECT EXPORTED StdioStreamToObject ( 
P UNKNOWN pFile) ; 
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This file contains the API for UUID routines. The functions described in this file are contained in 

PENPOINT.LIB. 

This file contains macros for creating and testing Nil and Invalid UUIDs, to compare two UUIDs for 

equality, and to create a well known UUID and a function to create dynamic uuids. 

UUID is an acronym for Universal Unique ID. 

#ifndef UUID_INCLUDED 
tdefine UUID_INCLUDED 

Include files 

tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 



Common #clefines and typedefs 



Macros 



For setting and testing for a Nil UUID 



#def ine MakeNilUUID (uuid) 
#define NilUUID (uuid) 



( (uuid) .machine = (uuid). id = OL) 

(((uuid) .machine == OL) && ((uuid). id == OL) ) 



For setting and testing for an invalid UUID 



#def ine MakelnvalidUUID (uuid) 
#def ine InvalidUUID (uuid) 



((uuid) .id = (uuid) .machine = maxU32) 
((uuid) .id == maxU32 && \ 
(uuid) .machine == maxU32) 



To compare two UUIDs for equality 
#define SameUUIDs(a,b) 



(((a) .machine == (b) .machine) && \ 
((a), id == (b).id)) 



To set the fields of a well known uuid 

♦define MakeWknUUID (uuid, tag, i) \ 

( (uuid) .machine = (tag), (uuid). id = (U32)(i)) 



Typedefs 



typedef struct UUID { 

U32 

U32 
} UUID, *P UUID; 



id; // Unique counting value 

machine; // Unique machine identifier 
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Public Functions 



MakeDynUUID 

Creates a dynamic UUID. 
Returns nothing. 



m Profolype void EXPORTED MakeDynUUID ( 

P_UUID pUUID 

); 



m 
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clsVolume inherits from clsObject. 

Provides volume support. 

Information in this file is useful if you are writing an installable volume. Also see volgodir.h for 

additional information. 

tifndef VOL_INCLUDED 
tdefine VOL_INCLUDED 

Include file dependencies 

tifndef GO_INCLUDED 

tinclude <go.h> 

tendif 

tifndef OS_INCLUDED 

tinclude <os.h> 

#endif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef FS_INCLUDED 

tinclude <fs.h> 

tendif 



Common #clefiiies and typedefs 



Defines 



tdefine fsDirPosFirst 
tdefine VOL METHOD 



(U32)0 

STATUS EXPORTED 



Flag to direct VNCreate to create short directory names (See VNCreate) 

tdefine fsShortDirName fsNodeReadOnly 

Error status codes 

tdefine stsNoMoreBuffers MakeStatus (clsVolume, 1) 

Informational status codes 

tdefine stsVolFormatlsTimeConsuming MakeWarning (clsVolume, 1) 

Resource ids for volume icons 

Defined with MakeWknResId (clsVolume, tag) 

Stored in groups of 10 values: 

Base value defines large icon, 

+ 1 value defines smaller icon, 

+2 thru +9 reserved for future. 



tdefine tagVolHardDisklcon 
tdefine tagVolFloppyDisklcon 
tdefine tagVolRemotePCIcon 
tdefine tagVolRemoteMacIcon 



// 1-9 define variants, see above 

10 // 11-19 define variants, see above 

20 // 21-29 define variants, see above 

30 // 31-39 define variants, see above 
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typedef OBJECT VOL; 

typedef P_FS_ATTR_SIZE *PP_FS_ATTR_SIZE; 

typedef P_FS_ATTR_LABEL *PP_FS_ATTR_LABEL; 

typedef U32 FS_ATTR_VALUE, *P_FS_ATTR_VALUE, **PP_FS_ATTR_VALUE; 

typedef U32 VOL_VNODE, *P_VOL_VNODE ; 

typedef struct DIR_ID_CACHE { 

} 



P MEM 


pBuf; 


// 


U32 


used; 


// 


U32 


free; 


// 


:r_id_cache; 






idef Struct VOL_CACHE { 




VOL VNODE 


vnodeNotKnown; 


// 


P_MEM 


pRoot ; 


// 


DIR_ID_CACHE 


dirlds; 


// 


OS_MILLI SECONDS 


lastAccess; 


// 


OS_MILLISECONDS 


lastVolAccess; 


// 


OS_MILL I SECONDS 


lastVolWrite; 


// 


OS MILLISECONDS 


refreshRate; 


// 



Sorted array of vol dir ids 
Number used, of allocated space 
Number free, of allocated space 



OS MILLISECONDS 



U16 



U16 



U16 



U16 



U16 



U16 



U16 



U16 



P_MEM 

P_MEM 

P_MEM 

U32 

U32 

U8 



U8 
U16 
U32 
} VOL CACHE; 



flushRate; 



Used to fake volRAM 
Cache dir elem for root vnode 
Dir id cache 

Last access to cache layer 
Last access to volume 
Last write to volume 
Check with volume this often 
// to see if volume has changed 
// since last vol access 
// maxU32 implies unchangeable 
// Flush cached dirty files 
// after this much time has passed 
// implies flush immediately 
// maxU32 implies no flushing 
// Default is 2000 (2 sees) 

Total num of dirs in the cache 
Includes both open and closed 
Total num of files in the cache 
Includes both open and closed 
Num of dirs in the cache 
that are opened on the vol 
Num of files in the cache 
that are opened on the vol 
Num of opened dirs that have 
non-zero reference counts 
Num of opened files that have 
non-zero reference counts 
Max dirs that can be left open 
for caching purposes . 
implies no dirs 
maxUl6 implies as many as wanted 
Default is maxU16 
Max files that can be left open 
for caching purposes . 
implies no files 
// maxUl6 implies as many as wanted 
Default is maxUl6 
First cache entry 
Last cache entry 
Write is to this cache entry 
Write at this position 
Write for this amount 
readDirFullInProgress ; 

// If non-zero then fully cached 
// dirs will not be "purged" . 
spareUS; 
spareU16; 
spares [5] ; 



numDirs; 


// 




// 


numFiles; 


// 




// 


openDirs; 


// 




// 


openFiles; 


// 




// 


refdDirs; 


// 




// 


refdFiles; 


// 




// 


maxOpenDirs ; 


// 




// 




// 




// 




// 


maxOpenFiles; 


// 




// 




// 




// 




// 


pFirst; 


// 


pLast; 


// 


pWrite; 


// 


writePos; 


// 


writeAmt ; 


// 
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Enuml 6 ( VOL_CMN_FLAGS ) { 

vcVolIsOnBootDevice = flagO, 



vcVolIsDetachable = flagl, 
vcVol Is Swap Volume = flag2 



// This volume is on the boot 

// device (as defined by the MIL) 

// but isn't necessarily THE boot 

// volume. 

// This volume is not removable 

// but may be detachable. 

// This is the swap volume. 



{ 



*pRtns; 
fsSema; 
volSema; 
flags; 
vnodeCount ; 
vnodeHeap; 
spare 1; 
dhCount ; 
dhHead; 
spare2 ; 
f hCount ; 
fhHead; 
cache ; 

dirlndexFile; 
dirlndexFileVerified; 
spare ; 
spares [5] ; 



}; 

typedef struct VOL_COMMON 

struct VOL_RTNS 

OS_SEMA_ID 

OS_SEMA_ID 

VOL_CMN_FLAGS 

U16 

OS_HEAP_ID 

U16 

U16 

P_MEM 

U16 

U16 

P_MEM 

VOL_CACHE 

OBJECT 

BOOLEAN 

U16 

U32 
} VOL_COMMON; 

typedef struct VOL_INFO { 

Struct VOL_INFO *pNext; 

F S_VOL_HEADER hdr ; 

VOL_COMMON cmn; 

// Volume specific vollnfo struct goes here... 
} VOL_INFO, *P_VOL_INFO, * *PP_VOL_INFO ; 

Enuml6(VN0DE_ACCESS) { 
// Delete node at handle free time? 

vnodeTemp = flagO, 
// Read/write intentions for this handle 

vnodeReadOnly = flag2, 
// Upper byte: exclusivity requirements 

vnodeNoExclusivity =MakeU16(0, 0), 

vnodeDenyWr iters =MakeU16(0, 1), 

vnodeExclusiveOnly =MakeU16(0, 2), 
// Uncompress file at VNGet time? 

vnodeUncompress = flagl4, 
// Default 

vnodeDefaultAccess = // perm, read/write, noExclusivity 
}; 
#define vnodelgnoreAccessInfo 0x8000 

typedef struct VNODE_CMN_ATTRS { 

FS_NODE_FLAGS nodeFlags; 

FS_DATE_TIME nodeCreated; 

FS_DATE_TIME nodeModified; 
} VNODE_CMN_ATTRS, *P_VNODE_CMN_ATTRS; 

Enuml 6 ( VNODE_ATTR_FLAGS ) { 

vnAttrNodeFlags = flagO, 
vnAttrNodeCreated = flagl, 
vnAttrNodeModified = flag2, 
vnAttrLabelsBuffer = flagS, 
vnAttrValuesBuffer = flag9, 
vnAttrSizesBuffer = flaglO 
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^Typedefs for functions supported by each 
volume class 

^ Volume related functions follovs^: 
VolStatus 

Has a volume check for readiness. 

Returns STATUS. 

Fyncfiori Prototype typedef STATUS FunctionPtr{P_VOL_STATUS) ( 
P_VOL_INFO pVolInfo, 

P_BOOLEAN pChanged // In/Out: Has volume changed? 

); 

#define VolStatus (pVolInfo, pChanged) \ 
( (pVolInfo) ->cnin.pRtns->pVolStatus) \ 
(pVolInfp, pChanged) 



ments 



Possible return status are stsOK, stsFSVolDisconnected, other errors. If status is okay, should indicate if 
volume has changed. 

Has a volume change its volume name. 
Returns STATUS. 

typedef STATUS FunctionPtr(P_VOL_SET_VOL_NAME) ( 

P_VOL_INFO pVolInfo, 

P_STRING pName // New volume name 

); 
fdefine VolSetVolName (pVolInf o, pName) \ 

((pVolInfo)->cmn,pRtns->pVolSetVolName) \ 
(pVolInfo, pName) 



VolUpdateVolInfo 

Requests that a volume updates its user accessable volume info. 

Returns STATUS. 

typedef STATUS FunctionPtr(P_VOL_UPDATE_VOL_INFO) ( 
P_VOL_INFO pVolInfo // Vol Info 

); 
#define VolUpdateVolInf o (pVolInf o) \ 

( (pVolInfo) ->cmn.pRtns->pVolUpdateVolInfo) \ 
(pVolInfo) 



VolSpecificMsg 

Passes a volume specific message down to a volume. 

Returns STATUS. 

¥umtmn Prototype typedef STATUS FunctionPtr (P_VOL_SPECIFIC_MSG) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

MESSAGE msg, // Message 

P_UNKNOWN pArgs // In/Out: Arguments for message 

); 

tdefine VolSpecificMsg (pVolInfo, vnode, msg, pArgs) \ 
( (pVolInfo) ->cmn.pRtns->pVolSpecificMsg) \ 
(pVolInfo, vnode, msg, pArgs) 
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Common vnode access/release functions follovs^: 
VNGet 

Gets a vnode given pVolInfo, dirVNode and name of node in the directory. 

Returns STATUS. 

tiers Prototype typedef STATUS FunctionPtr (P_VNODE_GET) ( 

P_VOL_INFO pVolInfo, // Vol Info 

VOL_VNODE dirVNode, // VNode of parent directory 

P_STRING pName, // Name of node in directory 

VNODE_ACCESS access, // R/W access, exclusivity, etc 

P_UNKNOWN pVolSpecific, // Vol specific info 

P_VOL_VNODE pVNode // Out: Returned vnode handle 

); 

tdefine VNGet (pVolInfo, dirVNode, pName, access, pVolSpecific, pVNode) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeGet) \ 

(pVolInfo, dirVNode, pName, access, pVolSpecific, pVNode) 

VNNextChild 

Gets a vnode given pVolInfo, dirVNode and dir position in a directory. 

Returns STATUS. 

tisn Protcfyps typedef STATUS FunctionPtr(P_VNODE_NEXT_CHILD) ( 

P_VOL_INFO pVolInfo, // Vol Info 

VOL_VNODE dirVNode, // VNode of parent directory 

P_U32 pDirPos, // In/Out: directory position data 

VNODE_ACCESS access, // R/W access, exclusivity, etc 

P_STRING pName, // Out: Name of node 

P_VOL_VNODE pVNode // Out: VNode handle 

); 

#define VNNextChild (pVolInfo, dirVNode, pDirPos, access, pName, pVNode) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeNextChild) \ 

(pVolInfo, dirVNode, pDirPos, access, pName, pVNode) 

VNGetByDirld 

Gets the vnode of a directory (and its name) given its directory id. 

Returns STATUS. 

lies PmiMyps typedef STATUS FunctionPtr (P_VNODE_GET_BY_DIR_ID) ( 

// Vol Info 

// VNode of parent directory 
// Dir id of directory 
// Out: Name of node 
_ _ // Out: Returned dir vnode handle. 

); 

tdefine VNGetByDirld (pVolInfo, dirVNode, dirld, pName, pVNode) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeGetByDirId) \ 
(pVolInfo, dirVNode, dirld, pName, pVNode) 



P_VOL_INFO 


pVolInfo, 


VOL VNODE 


dirVNode, 


U32 


dirld. 


P_STRING 


pName, 


P_VOL_VNODE 


pVNode 
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___ 

Increments the reference count on a vnode. 

Returns STATUS. 

»mfofype typedef STATUS FunctionPtr (P_VNODE_DUP) ( 

P_VOL_INFO pVolInfo, // Vol Info 

VOL_VNODE vnode, // The vnode being dupped 

VNODE_ACCESS access // R/W, exclusivity, etc. 

); 

#define VNDup(pVolInfo, vnode, access) \ 
( (pVolInfo) ->cmn .pRtns->pVNodeDup) \ 
(pVolInfo, vnode, access) 

VNRelea^e 

Returns a vnode to the volume. 

Returns STATUS. 

lion Pmfotype typedef STATUS FunctionPtr (P_VNODE_RELEASE) { 

P_VOL_INFO pVolInfo, // Vol Info 
VOL_VNODE vnode // The vnode being released 
); 
fdefine VNRelease (pVolInfo, vnode) \ 

( (pVolInfo) ->cmn.pRtns->pVNodeRelease) \ 
(pVolInfo, vnode) 

Directory handle related functions follows: 
VNCreate 

Creates a new file or directory node in the given (directory) node. 

Returns STATUS. 

lion Prototype typedef STATUS FunctionPtr (P_VNODE_CREATE) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE dirVNode, // Handle of directory vnode 

P_STRING pName, // Name of the new file 

FS_NODE_FLAGS type // File or directory? 

); 

#define VNCreate (pVolInfo, dirVNode, pName, type) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeCreate) \ 
(pVolInfo, dirVNode, pName, type) 

meiTts Note: the parameter type only uses the flag fsNodeDir to distinguish between directories and files and 

the flag fsShortDirName to direct the volume to use a short name replacement for the directory name. 
Directories are only shortened if they reside in the PenPoint tree. The flag fsShortDirName overlaps 
fsNodeReadOnly, which is never used in conjunction with directories. 
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VNDelete 

Deletes the given node. 

Returns STATUS. 

tofype typedef STATUS FunctionPtr {P_VNODE_DELETE) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // VNode to delete 

BOOLEAN visible // At root of hierarchical delete? 

); 

#define VNDelete (pVolInfo, vnode, visible) \ 
{ (pVolInfo) ->cinn.pRtns->pVNodeDelete) \ 
(pVolInfo, vnode, visible) 

VNode may be returned differently to mark it as a vnode that points to a deleted vnode. 

VNMove 

Moves/renames a node (and any children) to a new node. 

Returns STATUS. 

fotype typedef STATUS FunctionPtr {P_VNODE_MOVE) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE srcDirVNode, // Handle of dir node of source 

VOL_VNODE srcVNode, // Handle of source vnode of move 

VOL_VNODE dstDirVNode, // Handle of dir node of dest 

P_STRING pDstName // New name to give the node 

); 

tdefine VNMove (pVolInfo, srcDirVNode, srcVNode, dstDirVNode, pDstName) \ 
{ (pVolInfo) ->cmn.pRtns->pVNodeMove) \ 

(pVolInfo, srcDirVNode, srcVNode, dstDirVNode, pDstName) 



VNDirPosDeleteAdjust 

Makes any necessary adjustment to the dirPos after a node has been deleted. 

Returns STATUS. 

Fyocfiosi Profetype typedef STATUS FunctionPtr (P_VNODE_DIR_POS_DEL_ADJ) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE dirVNode, // Handle of directory vnode 

VOL_VNODE vnode, // Handle of deleted vnode 

P_U32 pDirPos // Dir position data before delete 

); 

#define VNDirPosDeleteAdjust (pVolInfo, dirVNode, vnode, pDirPos) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeDirPosDelAdj) \ 
(pVolInfo, dirVNode, vnode, pDirPos) 

.... ...... VNGetDirld 

Gets a directory node's dir id, given the vnode. 

Returns STATUS. 

Foncfion Prototype typedef STATUS FunctionPtr (P_VNODE_GET_DIR_ID) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

P_U32 pDirld // In/Out: dir id of dir node 

); 

#define VNGetDirld (pVolInfo, vnode, pDirld) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeGetDirId) \ 
(pVolInfo, vnode, pDirld) 
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File handle related functions follov^: 

Transfers n bytes from position m in a file to a buffer. 

Returns STATUS. 

Function Prototype typedef STATUS FunctionPtr (P_VNODE_READ) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 
U32 filePos, // Starting point of read 

U32 numBytes, // Number of bytes to be read 

P_U8 pReadBuffer, // Destination of bytes read 

P_U32 pCount // In/Out: Actual bytes read 

); 

Idefine VNRead(pVolInfo, vnode, filePos, numBytes, pReadBuffer, pCount) \ 
( (pVolInfo) ->cmii.pRtns->pVNodeRead) \ 

(pVolInfo, vnode, filePos, numBytes, pReadBuffer, pCount) 

VNWrite^ 

Transfers n bytes from a buffer to position m in a file. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_VNODE_WRITE) { 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

U32 filePos, // Starting point of the write 

U32 numBytes, // Number of bytes to write 

P_U8 pWriteBuffer, // Destination of bytes to write 

P_U32 pCount // In/Out: Actual bytes written 

); 

#define VNWrite (pVolInf o, vnode, filePos, numBytes, pWriteBuffer, pCount) \ 
( (pVolInf o) ->cmn .pRtns->pVNodeWrite) \ 

(pVolInfo, vnode, filePos, niimBytes, pWriteBuffer, pCount) 



VNGetSize 

Gets a node's size given the vnode. 

Returns STATUS. 

typedef STATUS FunctionPtr (P_VNODE_GET_SIZE) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

P_FS_FILE_SIZE pFileSize // In/Out: Node's size 

); 

tdefine VNGetSize (pVolInfo, vnode, pFileSize) \ 
( (pVolInfo)->cmn.pRtns->pVNodeGetSize) \ 
(pVolInfo, vnode, pFileSize) 
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VNSetSize 

Sets a node's size given the vnode and the new size. 

Returns STATUS. 

jncfieo Prolotype typedef STATUS FunctionPtr(P_VNODE_SET_SIZE) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

FS_FILE_SIZE fileSize // Node's new size 

); 

tdefine VNSetSize (pVolInfo, vnode, fileSize) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeSetSize) \ 
(pVolInfo, vnode, fileSize) 

smnierifs This function could be used to either truncate or grow the file/resFile. 

Attribute related functions follov^: 

VNGetName 

Gets a node's name, given the vnode. 

Returns STATUS. 

mcfiari Pmtofyfie typedef STATUS FunctionPtr (P_VNODE_GET_NAME) { 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

P_STRING pName // In/Out: name of node 

); 

tdefine VNGetName (pVolInfo, vnode, pName) \ 
{ (pVolInfo) ->cmn.pRtns->pVNodeGetName) \ 
(pVolInfo, vnode, pName) 

VNGetNumAttrs 

Returns the number of non-standard attributes, given the vnode. 

Returns STATUS. 

iiicfi«ii Prototype typedef STATUS FunctionPtr (P_VNODE_GET_NUM_ATTRS) ( 
P_VOL_INFO pVolInfo, 

VOL_VN0DE vnode, // Handle of vnode 

P_U16 pNumAttrs // Out: num of attrs to get 

); 

#define VNGetNumAttrs (pVolInfo, vnode, pNumAttrs) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeGetNumAttrs) \ 
(pVolInfo, vnode, pNumAttrs) 

VNGetAttrlnfo 

Returns a node's attributes, given the vnode. 

Returns STATUS. 

itKfbn Prototype typedef STATUS FunctionPtr (P_VNODE_GET_ATTR_INFO) ( 

P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

U16 num, // Num of attrs to get 

VNODE_ATTR_FLAGS flgs, // Get which attrs 

P_VNODE_CMN_ATTRS pCmn, // Common attrs 

P_U8 pWhich, // Which user defined attrs 

P FS ATTR LABEL pLbls, // In/Out: attribute labels 
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P_FS_ATTR_VALUE pVals, // In/Out : attribute values 

P_FS_ATTR_SIZE pSizs // In/Out: attribute sizes 

); 

#define VNGetAttrInfo(pVolInfo, vnode, num, figs, pCmn, pWhich, pLbls, pVals, pSizs) \ 
( (pVolInfo)->cmn.pRtns->pVNodeGetAttrInfo) \ 

(pVolInfo, vnode, num, figs, pCmn, pWhich, pLbls, pVals, pSizs) 

Coitimerits Which common attributes and which arrays of the label/value/size arrays that need to be filled in are 

defined by the flgs field. Which particular elements of each (label/value/size) array to be filled in is 
defined by the pWhich byte array. If num is or pWhich is null then no label/value/size array elements 
should be filled in. If an element of pWhich is maxU8 then the corresponding label/value/size array 
element should be filled in. If the data is known and set then the pWhich array element should be set to 
1 afiier setting the values. 

'"Ws7^ttrIn?o~™~~~^^~~""^^ 

Sets a node's attributes, given the vnode. 
Returns STATUS. 

Fiincti»r^ Prefotype typedef STATUS FunctionPtr(P_VNODE_SET_ATTR_INFO) ( 

// Handle of vnode 
// Num of attrs to set 
// Set which attrs 
// Common attrs 
// Which user defined attrs 
// In/Out: attribute labels 
// In/Out: attribute values 
_ _ _ // In/Out: attribute sizes 

); 

#define VNSetAttrInfo(pVolInfo, vnode, num, figs, pCmn, pWhich, pLbls, pVals, pSizs) \ 
( (pVolInfo) ->cmn.pRtns->pVNodeSetAttrInfo) \ 

(pVolInfo, vnode, num, figs, pCmn, pWhich, pLbls, pVals, pSizs) 

Which common attributes and which arrays of the label/value/size arrays that need to be stored are 
defined by the flgs field. Which particular elements of each (label/value/size) array to be filled in is 
defined by the pWhich byte array. If num is or pWhich is null then no label/value/size array elements 
should be stored. If an element of pWhich is maxU8 then the corresponding label/value/size array 
element should be stored. If the data is stored successfully then the pWhich array element should be set 
to 1. 

VNMakeNative 

Gets rid of all concepts not native to a file system (ie res/info fields) and return the native form name of 
the file afi:er being "stripped". 

Returns STATUS. 

typedef STATUS FunctionPtr(P_VNODE_MAKE_NATIVE) ( 

P_VOL_INFO pVolInfo, 

VOL_VNODE vnode, // Handle of vnode 

P_STRING pName // In/Out: Return buffer for native name 

); 
♦define VNMakeNative (pVolInfo, vnode, pName) \ 

( (pVolInfo) ->cmn .pRtns->pVNodeMakeNative) \ 
(pVolInfo, vnode, pName) 
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Misc functions follov/: 

___.___._.._^^^^ ..„„. , ^ 

Flushes all buffers associated with this vnode. 

Returns STATUS. 

:fiosi Prototype typedef STATUS FunctionPtr (P_VNODE_FLUSH) ( 
P_VOL_INFO pVolInfo, 

VOL_VNODE vnode // Handle of vnode 

); 
tdefine VNFlush(pVolInfo, vnode) \ 

( (pVolInfo) ->cmn.pRtns->pVNodeFlush) \ 
(pVolInfo, vnode) 

DirldGetParent 

Gets the dir id of the parent of a node (also identified by dir id). 

Returns STATUS. 

:ticn Prototype typedef STATUS FunctionPtr (P_DIRID_GET_PARENT) ( 
P_VOL_INFO pVolInfo, 

U32 node, // Node identified by dir id 

P_U32 pParent, // In/Out: dir id of parent 

P_BOOLEAN pParentlsRoot // In/Out: parent is root 
); 

♦define DirldGetParent (pVolInfo, node, pParent, pParentlsRoot) \ 
( (pVolInfo) ->cmn.pRtns->pDirIdGetParent) \ 
(pVolInfo, node, pParent, pParentlsRoot) 



Debugging functions follovN^: 



VNRefCount 

Gets the volume's ref count for a vnode. 

Returns STATUS. 

;tlc.n Prototype typedef STATUS FunctionPtr (P_VNODE_REF_COUNT) ( 

P_VOL_INFO pVolInfo, // Vol Info 

VOL_VNODE vnode, // The vnode to get info about 
P_U16 pRefCount // Out: Reference count on vnode 

); 

tdefine VNRefCount (pVolInfo, vnode, pRefCount) \ 
( (pVolInfo) ->cnui .pRtns->pVNodeRef Count) \ 
(pVolInfo, vnode, pRefCount) 

This is the definition for the table of volume routines: 

typedef struct VOL_RTNS { 
// Vol General. . . 

P_VOL_STATUS pVolStatus; 

P_VOL_SET_VOL_NAME pVolSetVolNaitie ; 

P_VOL_UPDATE_VOL_INFO pVolUpdateVolInfo; 

P_VOL_SPECIFIC_MSG pVolSpecificMsg; 
// VNode Access. . . 

P_VNODE_GET pVNodeGet; 

P_VNODE_NEXT_CHILD pVNodeNextChild; 

P_VNODE_GET_BY_DIR_ID pVNodeGetByDirld; 

P_VNODE_DUP pVNodeDup; 
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P_VNODE_RELEASE pVNodeRelease; 
// Directory Handle Related. . . 

P_VNODE_CREATE pVNodeCreate; 

P_VNODE_DELETE pVNodeDelete; 

P_VNODE_MOVE pVNodeMove; 

P_VNODE_DIR_POS_DEL_AD J pVNodeDirPosDelAd j ; 

P_VNODE_GET_D IR_ID pVNodeGe t D i r I d ; 
// File Handle Related. . . 

P_VNODE_READ pVNodeRead; 

P_VNODE_WRI TE pVNodeWr i t e ; 

P_VNODE_GET_SIZE pVNodeGetSize; 

P_VNODE_SET_SIZE pVNodeSetSize; 
// Attributes. . . 

P_VNODE_GET_NAME pVNodeGetName ; 

P_VNODE_GET_NUM_ATTRS pVNodeGetNumAt t r s ; 

P_VNODE_GET_ATTR_INFO pVNodeGet Att r Inf o ; 

P_VNODE_SET_ATTR_INFO pVNodeSetAttrlnfo; 

P_VNODE_MAKE_NAT I VE pVNodeMakeNat i ve ; 
// Misc. . . 

P_VNODE_FLUSH pVNodeFlush; 

P_DIRID_GET_PARENT pDirldGetParent; 
// Debugging. . . 

P_VNODE_REF_COUNT pVNodeRe f Count ; 
// Spares. . . 

P_UNKNOWN pSparel; 

P_UNKNOWN pSpare2; 

P_UNKNOWN pSpare3; 
} VOL_RTNS, *P_VOL_RTNS; 

Class FileSystem Messages 

These messages are used by volume code 

msgFSRegisterVolClass 

Registers a volume class with the file system. 

Takes P_FS_REGISTER_VOL_CLASS, returns STATUS. 

#define msgFSRegisterVolClass MakeMsg(clsFileSystem, 0) 

jmenfs typedef struct FS_REGISTER_VOL_CLASS { 

CLASS volClass; // Vol class of volume 

FS_VOL_TYPE volType; // Type of volume 

} FS_REGISTER_VOL_CLASS, *P_FS_REGISTER_VOL_CLASS; 

msgFSInstallVol 

Creates a volume's root dir handle and register it with the file system. 

Takes P_FS_INSTALL_VOL, returns STATUS. 

jmerits typedef struct FS_INSTALL_VOL { 

OBJ_KEY key; // Volume's key. 

CLASS volClass; // Class of the volume. 

VOL_VNODE vnode; // Root directory vnode. 

P_VOL_INFO pVolInfo; // In/Out: Volume info block. 

} FS_INSTALL_VOL, *P_FS_INSTALL_VOL; 

iffieits The volume should mark itself as connected and all observers of theFileSystem will be notified that a 

volume has been installed. (Note: The message is defined in fs.h so observers can use it.) 

#defme msgFSInstallVol MakeMsg(clsFileSystem, 1) 
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Arqwmeiifs 



Comments 
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Comments 



msgFSRemoveVol 

Removes a volume from the file system and destroy its root dir handle. 
Takes P_FS_REMOVE_VOL, returns STATUS. 



typedef struct FS_REMOVE_VOL { 
OBJ_KEY key; 

CLASS vOlClass; 

P_VOL_INFO pVolInfo; 

} FS REMOVE VOL, *P FS REMOVE VOL; 



// Volume' s key. 

// Class of the volume. 

// Volume info block. 



Observers of theFileSystem will be notified of the change. (Note: The message is defined in fs.h so 
observers can use it.) 

#defme msgFSRemoveVol MakeMsg(clsFileSystem, 2) 

msgFSConnectVol 

Marks a volume as connected and notify observers of theFileSystem. 
Takes P_FS_CONNECT_VOL, returns STATUS. 



typedef struct FS_CONNECT_VOL { 

P_VOL_INFO pVolInfo; 
} FS CONNECT VOL, *P FS CONNECT VOL; 



// Volume info block. 



(Note: The message is defined in fs.h so observers can use it.) 
#define msgFSConnectVol MakeMsg(clsFileSystem, 3) 



msgFSDisconnectVol 

Marks a volume as disconnected and notify observers of theFileSystem. 

Takes P_FS_DISCONNECT_VOL, returns STATUS. 

typedef struct FS_DISCONNECT_VOL { 

P_VOL_INFO pVolInfo; // Volume info block. 

} FS_DISCONNECT_VOL, *P_FS_DISCONNECT_VOL; 

(Note: The message is defined in fs.h so observers can use it.) 

#define msgFSDisconnectVol MakeMsg(clsFileSystem, 4) 



msgFSVolList 

Returns device list for given class and count of volumes of that class 
Takes P_FS_VOL_LIST, returns STATUS. 
#define msgFSVolList 



Enuml6(FS_V0L_LIST_ACCESS) { 
fsAccessVolList = 0, 
fsReleaseVolList = 1, 
fsGetHeadOfVolList = 2 

}; 

typedef struct FS_VOL_LIST { 

FS_VOL_LIST_ACCESS access; 
OBJECT volClass; 

U16 volCount; 

P_VOL_INFO pVolInfo; 

} FS VOL LIST, *P FS VOL LIST; 



MakeMsg(clsFileSystem, 5) 

// Also returns head of list, 



// See above. 

// Class of the volumes. 

// Out: Number of volumes. 

// Out: First vol info block. 
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msgFSUnRegisterVolClass 

UnRegisters a volume class from the file system. 

Takes P_CLASS, returns STATUS. 

tdefirie msgFSUnRegisterVolClass MakeMsg(clsFileSystem, 6) 

msgFSVolIsBusy 

Checks to see if a volume can be removed. 

Takes P_FS_VOL_INFO, returns STATUS*. 

tdefine msgFSVolIsBusy Ma]ceMsg(clsFileSystem, 7) 

If no user files/dirs are open and all caches have been written to the volume then the volume may be 
removed. This method should only be called by the volume to be removed. 

If the volume can be removed then stsOK is returned. If the volume can not be removed then 
stsFSVolBusy is returned. 

msgFSExclVolAccess 

Allows a volume class to obtain exclusive access to a volume and to release the exclusive access. 

Takes P_FS_EXCL_VOL_ACCESS, returns STATUS. 

#define msgFSExclVolAccess Ma]ceMsg(clsFileSystem, 8) 

Enuml6(EXCL_V0L_ACCESS) { 

xvaAcquireVolIfNotBusy =1, // Acquire volume if not accessed 

xvaReleaseVol = 2 

}; 
typedef struct FS_EXCL_VOL_ACCESS { 

EXCL_VOL_ACCESS mode; 

P_VOL_INFO pVolInfo; 

} FS_EXCL_VOL_ACCESS, *P_FS_EXCL_VOL_ACCESS; 

This is used during the update volume list portions of volume classes. Volume classes should not try to 
update a volume if it is busy. 

If the volume was not busy and was acquired then stsOK is returned. If the volume was busy then a non 
StsOK is returned. 



Class Volume Messages 



msgVolUpdateVolumes 

Has the volume class update its list of volumes. 

Takes P_VOL_UPDATE_VOLUMES, returns STATUS. 

#define msgVolUpdateVolumes MakeMsg(clsVolume, 0) 

Enuml6(FS_UPDATE_V0LS_M0DE) { 
// An update should be done to all devices 

fsUpdateAllDevices = flagO, 
// The update request is in response to a power down notification 

fsUpdatePoweringDown = flagl, 
// The update request is in response to a power up notification 

fsUpdatePoweringUp = flag2, 
// Update searching for a volume? 

fsUpdateSearchingForVolume = flag3 
}; 



VOL.H 99 

Class Volume Messages Formatting 

typedef struct VOL_UPDATE_VOLUMES { 

FS_UPDATE_VOLS_MODE updateMode; // See above. 

U32 sparel; // For future use. 

U32 spare2; // For future use. 

} VOL_UPDATE_VOLUMES, *P_VOL_UPDATE_VOLUMES ; 

All volumes are sent this message every two seconds to give them a chance to do periodic volume 
updating. If the user has requested a disk/volume that is not connected then volumes are sent this 
message with the fsUpdateSearchingForVolume flag set. Volumes should not notify observers of volume 
connections, diconnections etc if a search is in progress. The notification should be deferred until a later 
update request is sent. If the user has triple tapped on the connections notebook, asking to update all 
volumes, then volumes are sent this message with the fsUpdateAllDevices flag set. 



Volume Specific Messages 



msgVolEjectMedia 

Has the volume eject its media. 
Takes void, returns STATUS. 

tdefine msgVolEjectMedia MakeMsg{clsVolume, 10) 

Comments Passed as a volume specific msg by the file system. 



msgVolInvalidateCaches 

Allows volumes to invalidate cache buffers at warm boot time. 
Takes void, returns STATUS. 

#define msgVolInvalidateCaches MakeMsg(clsVolume, 11) 

Passed as a volume specific msg by the file system at power up time. 

msgVolUpdateBootCode 

Reads image of boot sector from mil.res and stores onto boot sector. 
Takes void, returns STATUS. 

#define msgVolUpdateBootCode MakeMsg(clsVolume, 12) 

menfs Passed as a volume specific msg by the installation utility. 

Class Volume Messages Formatting 

msgVolFormatVolumelnit 

This msg is sent to a volume to initiate a reformat of the volume. 

Takes P_VOL_FORMAT_MEDIA_INIT, returns STATUS. 

tdefine msgVolFormatVolumelnit MakeMsg(clsVolume, 20) 

ments This initiates the format from the current owner of the block device. The volume object is destroyed 

(although there is a possibility that the destroy will fail) and then the block device of that volume, the 
volume offset on the block device and the volume size are returned. Call the volume class that is to 
format the volume with the message msgVolFormatMedialnit passing it this information. It will return 
a format id. 
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Note that all other format related messages are sent to the class of the volume, because the volume will 
no longer exist. 

msgVolFormatMedialnit 

Takes a block device object and returns a format id to be used with the other format messages. 

Takes P_VOL_FORMAT_MEDIA_INIT, returns STATUS. 

tdefine msgVolFormatMedialnit MakeMsg(clsVolume, 21) 

Hiiertfs typedef struct VOL_FORMAT_MEDIA_INIT { 

OBJECT blockDevice; // A block device 

U32 volumeOffset; // Format device beginning here 

U32 volumeSize; // Amount of device to be formatted 

P_UNKNOWN format Id; // Out: Format id 

} VOL_FORMAT_MEDIA_INIT, *P_VOL_FORMAT_MEDIA_INIT; 

meiifs NOTE: volumeOffset should be zero and volumeSize should be zero if you wish to format the entire 

device (vs a partition of the device). 

msgVolMediaCapacities 

Returns the possible format capacities for the device requesting format. 

Takes P_VOL_MEDIA_CAPACITIES, returns STATUS. 

Idefine msgVolMediaCapacities MakeMsg(clsVolume, 22) 

iRierifs typedef struct VOL_MEDIA_CAPACITIES { 

P_UNKNOWN formatid; // Format id from format/reformat. 

U16 maxCapacities; // Size of output capacities array. 

U16 numCapacities; // Out: Actual number of capacities. 

P_U32 pCapacities; // In/Out: Capacities. 

} VOL_MEDIA_CAPACITIES, *P_VOL_MEDIA_CAPACITIES; 

ments This messages is sent to the class of the volume. 

msgVolFormatMediaSetup 

Has the vol class set the media to be ready for a format and determines if the block device will require 
format media (vs format track). 

Takes P_VOL_FORMAT_MEDIA, returns STATUS. 

#define msgVolFormatMediaSetup MakeMsg(clsVolume, 23) 

Clients typedef struct VOL_FORMAT_MEDIA { 

P_UNKNOWN formatid; // Format id from format/reformat. 

U32 capacity; // Desired capacity to format for. 

P_STRING pName; // Name of re/formatted volume. 

U16 percentDone; // Out: Progress report. 

} VOL_FORMAT_MEDIA, *P_VOL_FORMAT_MEDIA; 

Rienfs This messages is sent to the class of the volume. 

msgVolFormatMediaBegin 

Has the vol class begin the format of its media. 

Takes P_VOL_FORMAT_MEDIA, returns STATUS. 

tdefine msgVolFormatMediaBegin MakeMsg(clsVolume, 24) 



Message 
Arguments 



Comments 



rtessoge 
l^rgwmetits 



Comments 



typedef struct VOL_FORMAT_MEDIA { 

P_UNKNOWN formatid; 

U32 capacity; 

P_STRING pName; 

U16 percentDone; 

} VOL FORMAT MEDIA, *P VOL FORMAT MEDIA; 
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// Format id from format/reformat. 

// Desired capacity to format for. 

// Name of re/ formatted volume. 

// Out: Progress report. 
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This step may do a format media if format track is not supported by tlie block device and may partition 
the media if it needs partitioning. 

This messages is sent to the class of the volume. 



msgVolFormatMediaCont 

Has the vol class do a format of its media. 

Takes P_VOL_FORMAT_MEDIA, returns STATUS. 

#define msgVolFormatMediaCont MakeMsg(clsVolume, 25) 



typedef struct VOL_FORMAT_MEDIA { 
P_UNKNOWN formatid; 

U32 capacity; 

P_STRING pName; 

U16 percentDone; 



// Format id from format/reformat. 
// Desired capacity to format for. 
// Name of re/ formatted volume. 
// Out: Progress report. 
} VOL_FORMAT_MEDIA, *P_VOL_FORMAT_MEDIA; 

If format track is supported then this step will format the next track. If the media was formatted during 
msgVolFormatMediaBegin then this will only do verifying of format. If percentDone is not 100, then 
keep calling this until it is. 

This messages is sent to the class of the volume. 



msgVolCancelFormat 

Has the vol class cancel the format. 
Takes P_UNKNOWN, returns STATUS. 

#define msgVolCancelFormat MakeMsg(clsVolume, 26) 

iments This messages is sent to the class of the volume. 

Class Volume Messages Duplicating 



imenfs 



msgVolDuplicateVolume 

This msg is sent to a volume to initiate a duplication of that volume. 

Takes PP_UNKNOWN, returns STATUS. 

tdefine msgVolDuplicateVolume MakeMsg(clsVolume, 30) 

A duplicate block is then allocated and a duplicateld that can be used with the other duplicate messages 
is returned. Note that the other messages are sent to the class of the volume. 



msgVolDuplicateMedia 

Has the volume class duplicate more of the disk. 

Takes P_VOL_DUPLICATE_MEDIA, returns STATUS. 

tdefine msgVolDuplicateMedia MakeMsg{ els Volume, 31) 
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typedef struct VOL_DUPLICATE_MEDIA { 

P_UNKNOWN duplicateld; // Duplicate id from duplicate. 

BOOLEAN sourceDisk; // Is this source or destination? 

U16 percentDone; // Out: Progress report. 

} VOL_DUPLICATE_MEDIA, *P_VOL_DUPLICATE_MEDIA; 

If source is TRUE then data will be read from the source disk. If source is FALSE then data is written to 
the destination disk. The value percentDone is updated to reflect how much of the duplication has been 
completed. If percentDone is not 100, then keep calling this until it is. 



msgVolDuplicateReady 

Checks to see if the source/dest disk of the duplicate is ready. 

Takes P_VOL_DUPLIQVTE_MEDIA, returns STATUS. 

tdefine msgVolDuplicateReady MakeMsg(clsVolume, 32) 



typedef struct VOL_DUPLICATE_MEDIA { 
merits P_UNKNOWN duplicateld; // Duplicate id from duplicate. 

BOOLEAN sourceDisk; // Is this source or destination? 

U16 percentDone; // Out: Progress report. 

} VOL_DUPLICATE_MEDIA, *P_VOL_DUPLICATE_MEDIA; 

Tients The return percentDone is unused. 

msgVolCancelDuplication 

Have the vol class cancel the duplication. 

Takes P_UNKNOWN, returns STATUS. 

tdefine msgVolCancelDuplication MakeMsg(clsVolume, 33) 



'k^ 
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VOLGODIR.H 



This file contains declarations for the common part of godir volumes. Examples of these include 

clsVolDisk and clsVolTOPS. 

Information in this file is useful if you are trying to understand the format of PenPoint.dir files or if you 

are writing an installable volume. 

tifndef VOLGODIR_INCLUDED 
tdefine VOLGODIR_INCLUDED 

Include file dependencies for this include file 

tifndef GO_INCLUDED 

#include <go.h> 

tendif 

#ifndef OS_INCLUDED 

#include <os.h> 

#endif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef FS_INCLUDED 

tinclude <fs.h> 

tendif 

tifndef VOL_INCLUDED 

tinclude <vol.h> 

tendif 

Common #def ines and typedefs 

Defines 

GO directory related defines 



tdefine goNamelndex 

tdefine goDirSearchFroiiiFirst 

tdefine goDirHeaderBufSize 




OL 



112 // Min space for 3 max names plus some 
Types 

General types 
Enumerated constants for searching for particular directory entries 

Enuml6(G0_DIR_FINDTYPE) { 

gdFindEmpty = 0, 

gdFindNextName = 1/ 

gdFindNativeName = 2, 

gdFindGoDirName = 3 
}; 
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Note that this can also be treated as an array of U32, using the tag part of the associated fsAttr as the 
index into the array, except flags and unused together form a special case of a U32!!! 

typedef struct VOLGODIR_CMN_ATTRS { 

FS_NODE_FLAGS flags; 

U16 unused; // Was sequence 

FS_DATE_TIME dateCreated; 

FS_DATE_TIME dateModified; 

FS_FILE_SIZE fileSize; 

} VOLGODIR_CMN_ATTRS, *P_VOLGODIR_CMN_ATTRS; 

GO directory related types 

Each directory entry is identified as either erased (e) or full (f). 

Enuml6(G0_DIR_ENTRY_TYPES) { 

goDirUnusedEntry = 'e', 

goDirNodeEntry = ' f 

}; 
typedef struct GO_DIR_USER_ATTR { 

FS_ATTR_LABEL label; // file system attribute label. 

U16 size; // size of value field. 

U8 value; // a U32, string or var length attr. 

} GO_DIR_USER_ATTR, *P_GO_DIR_USER_ATTR; 

typedef struct GO_DIR_ENTRY_HEADER { 

U8 type; // 'e': erased or 'f for file/dir. 

U16 size; // Actual size on disk is modulo 32. 

} GO_DIR_ENTRY_HEADER, *P_GO_DIR_ENTRY_HEADER; 

Go name is located at goDirEntry.buf, always the first entry. The define goNamelndex can be used to 
index to the name. It is important that the size of GO_DIR_ENTRY is modulo 32. 

typedef struct GO_DIR_ENTRY { 

GO_D IR_ENTRY_HEADER hdr ; 

U16 numUserAttrs; // Number of user attributes. 

U8 nativeName Index;// Offset to native file name. 

US rsrvdForLater; // UNUSED SPARE. 

US userAttrs Index; // Offset to first user attr. 

FS_NODE_FLAGS flags; 

U16 rsrvdForLater2; // WAS SEQUENCE 

FS_DATE_TIME dateCreated; 

US buf [goDirHeaderBufSize] ; // Min space for names. 

} GO_DIR_ENTRY, *P_GO_DIR_ENTRY, **PP_GO_DIR_ENTRY; 

VNode types 

VNode related type declarations 

Enuml6(V0LG0DIR_VN0DE_FLAGS) { 

gdfPenPointDir = flagl, // This is a PenPoint. Dir file 

gdfRootDir = flag2, 

gdfNodeCorrupt = flagS, 

gdfNodeModified = flag4, 

gdfHasGoDirParent = flagS, 

gdfHasGoDirSister = flag6, 

gdfNoGoDirSister = flag? 
}; 
typedef struct VOLGODIR_VNODE_COMMON { 

U16 ref Count; 

U16 numUserAttrs; 

U32 goDirPos; 

VOLGODIR_VNODE_FLAGS flags; 

VOLGODIR_CMN_ATTRS attrs; 
} VOLGODIR VNODE COMMON; 
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typedef struct VOLGODIR_VNODE { 

struct VOLGODIR_VNODE *pNext; 

VOLGODIR_VNODE_COMMON cmn; 
} VOLGODIR_VNODE, *P_VOLGODIR_VNODE, **PP_VOLGODIR_VNODE; R 

Penpoint dir cache 

typedef struct GO_DIR_CACHE { 

U32 size; // How much of data is valid? 

U32 base; // Position in penpoint dir. 

P_VOLGODIR_VNODE owner; // Cache for which dir. 

U8 buffer [512]; // Fixed size buffer. 

} GO_DIR_CACHE, *P_GO_DIR_CACHE; 

Vollnfo types 

This is the instance data for a GO dir volume object 

typedef struct VOLGODIR_INFO { 

// Common volume info... 

struct VOLGODIR_INFO *pNext; 

FS_VOL_HEADER hdr; 

VOL_COMMON cmn; 

// Pointer to the low level volumes routines... 

struct VOLGODIR_RTNS *pRtns; 

// Head of the vnode chain... 

P_VOLGODIR_VNODE pFirstVNode; 

// Buffer used by the GO DIR volume part - does not need to be inited. . . 

GO_DIR_ENTRY goDirEntry; 

//GO DIR buffer & info... 

GO_D IR_CACHE goDi rCache ; 

// Beyond this point each volume will have their own info. . . 

// . 

// . 

// . 
} VOLGODIR_INFO, *P_VOLGODIR_INFO; 

Exported routine that returns pointer GoDirShell entrypoint table 

lion Prototype P_VOL_RTNS EXPORTED GoDirShellEntrypoint (void) ; 

Typedefs for functions supported by each godir lower level volume 

LVStatus 

Has a volume check for readiness. 

Returns STATUS. 

lisii Prototype typedef STATUS FunctionPtr {P_LVOL_STATUS) ( 
P_VOLGODIR_INFO pVolInfo, 

P_BOOLEAN pChanged // In/Out: Has volume changed? 

); 

tdefine LVStatus (pVolInfo, pChanged) \ 
( (pVolInfo) ->pRtns->pLVolStatus) \ 
(pVolInfo, pChanged) 

merits Possible return status are stsOK, stsFSVolDisconnected, other errors. If status is okay, should indicate if 

volume has changed. 
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LVSetVolName 

Requests for a volume to set/change its volume name. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVOL_SET_VOL_NAME) ( 
P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_STRING pName // Vol name 

); 

♦define LVSetVolName (pVol Info, pName) \ 
( (pVolInfo) ->pRtns->pLVolSetVolName) \ 
(pVolInfo, pName) 

LVUpdatelnfo 

Requests for a volume to update its user accessable volume info. 

Returns STATUS. 

¥unefmn Pmioffpe typedef STATUS FunctionPtr {P_LVOL_UPDATE_INFO) ( 

P_VOLGODIR_INFO pVolInfo // Vol Info 

); 
#define LVUpdatelnfo (pVolInfo) \ 

( (pVolInf o) ->pRtns->pLVolUpdateInf o) \ 
(pVolInfo) 

LVSpecificMsg 

Passes a volume specific message down to a volume. 
Returns STATUS. 

typedef STATUS FunctionPtr {P_LVOL_SPECIFIC_MSG) ( 

P_VOLGODIR_INFO pVolInfo, 

P_VOLGODIR_VNODE pVNode, // Handle of vnode 

MESSAGE msg, // Message 

P_UNKNOWN pArgs // In/Out: Arguments for message 

); 
fdefine LVSpecificMsg (pVolInfo, pVNode, msg, pArgs) \ 

( (pVolInfo) ->pRtns->pLVolSpecif icMsg) \ 
(pVolInfo, pVNode, msg, pArgs) 

LVNGet 

Gets a vnode given pVolInfo, dirVNode and name of node in the directory. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_GET) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pDirVNode, // VNode of parent directory 

P_STRING pFileName, // Name of file node 

P_UNKNOWN pVolSpecific, // Vol specific info 

PP_VOLGODIR_VNODE ppVNode // Out: Returned vnode handle 

); 

#define LVNGet (pVolInfo, pDirVNode, pFileName, pVolSpecific, ppVNode) \ 
( (pVolInfo) ->pRtns->pLVNodeGet) \ 

(pVolInfo, pDirVNode, pFileName, pVolSpecific, ppVNode) 
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LVNGetAndOpenParent 

Gets a vnode's parent given pVolInfo and a vnode and open it. 
Returns STATUS. 

typedef STATUS FunctionPtr(P_LVNODE_GET_OPEN_PARENT) ( 
P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode to get parent of 

PP_VOLGODIR_VNODE ppDirVNode, // Out: VNode handle of parent 

P_BOOLEAN pComplete // Out: Did the vnode already exist? 

); 

tdefine LVNGetAndOpenParent (pVol Info, pVNode, ppDirVNode, pComplete) \ 
( (pVolInfo) ->pRtns->pLVNodeGetAndOpenParent) \ 
(pVolInfo, pVNode, ppDirVNode, pComplete) 

Gets a dir vnode given pVolInfo and tlie directory's dirlD. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_GET_OPEN_By_DIR_ID) ( 
P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pDirVNode, // VNode of parent of dir 

U32 dirld, // Dir ID of vnode to get & open 

PP_VOLGODIR_VNODE ppDirVNode, // Out: Returned vnode handle of dir 

P_BOOLEAN pComplete // Out: Did the vnode already exist? 

); 

tdefine LVNGetAndOpenByDirId(pVolInfo, pDirVNode, dirld, ppDirVNode, pComplete) \ 
( (pVolInf o) ->pRtns->pLVNodeGetAndOpenByDirId) \ 

(pVolInfo, pDirVNode, dirld, ppDirVNode, pComplete) 

Note: pDirVNode could be null. If it isn't then it can be used. 



LVNRelease 

Releases a vnode. 

Returns STATUS. 

Fyticlion Prototype typedef STATUS FunctionPtr (P_LVNODE_RELEASE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode // VNode to release 

); 
tdefine LVNRelease (pVolInfo, pVNode) \ 

( (pVolInfo) ->pRtns->pLVNodeRelease) \ 
(pVolInfo, pVNode) 

Opens a vnode. 

Returns STATUS. 

?^ynction Prottttyps typedef STATUS FunctionPtr (P_LVNODE_OPEN) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode to open 

P_STRING pName, // Name of node 

VNODE_ACCESS access // R/W, exclusivity, etc. 

); 

tdefine LVNOpen(pVolInfo, pVNode, pName, access) \ 
( (pVolInfo) ->pRtns->pLVNodeOpen) \ 
(pVolInfo, pVNode, pName, access) 
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LVNClose 

Closes a vnode. 

Returns STATUS. 

fioti Profoiype typedef STATUS FunctionPtr (P_LVNODE_CLOSE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode // VNode to close 

); 

fdefine LVNClose (pVol Info, pVNode) \ 
( (pVolInfo) ->pRtns->pLVNodeClose) \ 
(pVolInfo, pVNode) 



LVNCreate 

Creates a file or directory within the directory given. 

Returns STATUS. 

¥uncfmn Pmtt»fyp& typedef STATUS FunctionPtr(P_LVNODE_CREATE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pDirVNode, // Directory where new node belongs 
P_STRING pName, // Name of new file/dir 

FS_NODE_FLAGS fileType // Create a dir or a file 
); 

#define LVNCreate (pVol Info, pDirVNode, pName, fileType) \ 
( (pVolInfo) ->pRtns->pLVNodeCreate) \ 

(pVolInfo, pDirVNode, pName, fileType) 



LVNDelete 

Deletes a file system node; either a dir or a file node. 
Returns STATUS. 

Fyoctsoo Profofype typedef STATUS FunctionPtr (P_LVNODE_DELETE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 
P_VOLGODIR_VNODE pVNode, // VNode to release 
BOOLEAN visible // At root of hierarchical delete? 

); 

Idefine LVNDelete (pVolInfo, pVNode, visible) \ 
( (pVolInfo) ->pRtns->pLVNodeDelete) \ 
(pVolInfo, pVNode, visible) 

Moves a file or directory to a directory w/ the new (old) name. 

Returns STATUS. 

¥umtion Prototype typedef STATUS FunctionPtr (P_LVNODE_MOVE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pSrcDirVNode, // Dir of source node 
P_VOLGODIR_VNODE pSrcVNode, // Source node 

P_VOLGODIR_VNODE pDstDirVNode, // Dir of dest 
P_STRING pDstName // Name to give the dest node 

); 

♦define LVNMove (pVolInf o, pSrcDirVNode, pSrcVNode, pDstDirVNode, pDstName) \ 
{ (pVolInf o) ->pRtns->pLVNodeMove) \ 

(pVolInfo, pSrcDirVNode, pSrcVNode, pDstDirVNode, pDstName) 
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LVNReadDir 

Returns the next entry from the specified directory. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_READ_DIR) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pDirVNode, // Directory to read from 

P_U32 pDirPos, // In/Out; Current position 

P_STRING pName // Out: Name of the node 

); 

#define LVNReadDir (pVolInfo, pDirVNode, pDirPos, pName) \ 
( (pVolInfo) ->pRtns->pLVNodeReadDir) \ 

(pVolInfo, pDirVNode, pDirPos, pName) 

LVNDkPosbeleteAdjust~^ "^'^^ ^^ 

Makes any necessary adjustment to the dirPos after a node has been deleted. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_DIR_POS_DEL_ADJUST) { 
P_VOLGODIR_INFO pVolInfo, 

P_VOLGODIR_VNODE dirVNode, // Handle of directory vnode 

P_VOLGODIR_VNODE vnode, // Handle of deleted vnode 

P_U32 pDirPos // In/Out: Dir pos data before delete 

); 

tdefine LVNDirPosDeleteAdjust (pVolInfo, dirVNode, vnode, pDirPos) \ 
{ (pVolInfo) ->pRtns->pLVNodeDirPosDelAdjust) \ 
(pVolInfo, dirVNode, vnode, pDirPos) 

lAHNGetbirid^^^'^^^^^"^^^^"''^"^ ^^^^^^^^^^- - ..-..,....-..-.. 

Returns a well known constant dir id that represents this directory. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_GET_DIR_ID) { 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // Return dir id of this dir vnode 

P_U32 pDirld // In/Out: The directory's id 

); 
tdefine LVNGetDirId(pVolInfo, pVNode, pDirld) \ 

( (pVolInfo) ->pRtns->pLVNodeGetDirId) \ 
(pVolInfo, pVNode, pDirld) 

LVNN^r 

Returns the name a file system node. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_NAME) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode to get name of 

P_STRING pName // In/Out: Name 

); 
tdefine LVNName (pVolInf o, pVNode, pName) \ 

( (pVolInfo) ->pRtns->pLVNodeName) \ 
(pVolInfo, pVNode, pName) 
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LVNGetNumAttrs 

Returns the number of non-standard attributes, given the vnode. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_GET_NUM_ATTRS) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode of node to read from 

P_U16 pNumAttrs // Out: num of attrs to get 

); 
#define LVNGetNumAttrs (pVolInfo, pVNode, pNumAttrs) \ 

( (pVolInfo) ->pRtns->pLVNodeGetNumAttrs) \ 
(pVolInfo, pVNode, pNumAttrs) 



smtwents 



LVNGetAttrlnfo 

Gets a node's attributes, given the vnode. 
Returns STATUS. 



P_VOLGODIR_VNODE 

U16 

VNODE_ATTR_FLAGS 

P_VNODE_CMN_ATTRS 

P_U8 

P_FS_ATTR_LABEL 

P_FS_ATTR_VALUE 

P FS ATTR SIZE 



// VNode of node to read from 
// Num of attrs to get 
// Get which common attrs 
// Common attrs 
// Which user defined attrs 
// In/Out: attribute labels 
// In/Out: attribute values 
// In/Out: attribute sizes 



typedef STATUS FunctionPtr (P_LVNODE_GET_ATTR_INFO) ( 
P_VOLGODIR_INFO pVolInfo, // Vol Info 

pVNode, 
num, 
figs, 
pCmn, 
pWhich, 
pLbls, 
pVals, 
pSizs 
); 

#define LVNGetAttrlnfo (pVolInfo, pVNode, num, figs, pCmn, pWhich, pLbls, pVals, pSizs) \ 
( (pVolInfo) ->pRtns->pLVNodeGetAttrInfo) \ 

(pVolInfo, pVNode, num, figs, pCmn, pWhich, pLbls, pVals, pSizs) 

Which common attributes and which arrays of the label/value/size arrays that need to be filled in are 
defined by the figs field. Which particular elements of each (label/value/size) array to be filled in is 
defined by the pWhich byte array. If num is or pWTiich is null then no label/value/size array elements 
should be filled in. If an element of pWhich is maxU8 then the corresponding label/value/size array 
element should be filled in. If the data is known and set then the pWhich array element should be set to 
1 after setting the values. 



LVNSetAttrlnfo 

Sets a node's attributes, given the vnode. 
Returns STATUS. 

typedef STATUS FunctionPtr (P LVNODE 



P_VOLGODIR_INFO 

P_VOLGODIR_VNODE 

U16 

VNODE_ATTR_FLAGS 

P_VNODE_CMN_ATTRS 

P_U8 

P_FS_ATTR_LABEL 

P_FS_ATTR_VALUE 

P FS ATTR SIZE 



pVolInfo, 

pVNode, 

num, 

figs, 

pCmn, 

pWhich, 

pLbls, 

pVals, 

pSizs 



SET_ATTR_INFO) ( 
// Vol Info 

VNode of node to read 
Num of attrs to set 
Set which common attrs 
Common attrs 

Which user defined attrs 
In/Out: attribute labels 
In/Out: attribute values 
In/Out: attribute sizes 



// 
// 
// 
// 
// 
// 
// 
// 



from 



); 

#define LVNSetAttrlnfo (pVol Info, pVNode, num, 
( (pVolInfo) ->pRtns->pLVNodeSetAttrInfo) \ 

(pVolInfo, pVNode, num, figs, pCmn, pWhich, 



figs, pCmn, pWhich, pLbls, pVals, pSizs) \ 
pLbls, pVals, pSizs) 
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Which common attributes and which arrays of the label/value/size arrays that need to be stored are 
defined by the flgs field. Which particular elements of each (label/value/size) array to be filled in is 
defined by the pWhich byte array. If num is or pWhich is null then no label/value/size array elements 
should be stored. If an element of pWhich is maxU8 then the corresponding label/value/size array «« 

element should be stored. If the data is stored successfully then the pWliich array element should be 
set to 1 . 



tf) 



LVNRead 

Transfers n bytes from position m in a file to a buffer. 

Returns STATUS. 

Fyricfion Prototype typedef STATUS FunctionPtr (P_LVNODE_READ) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode of node to read from 

U32 filePos, // Starting point of read 

U32 numBytes, // Number of bytes to be read 

P_U8 pReadBuffer, // Destination of bytes read 

P_U32 pCount // Out: Actual number of bytes read 

); 

tdefine LVNRead (pVolInfo, pVNode, filePos, numBytes, pReadBuffer, pCount) \ 
{ (pVolInfo) ->pRtns->pLVNodeRead) \ 

(pVolInfo, pVNode, filePos, numBytes, pReadBuffer, pCount) 

Transfers n bytes from a buffer to position m in a file. 

Returns STATUS. 

Functbn Prototype typedef STATUS FunctionPtr (P_LVNODE_WRITE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 
P_VOLGODIR_VNODE pVNode, // VNode of node to write to 
U32 filePos, // Starting point of the write 

U32 numBytes, // Number of bytes to write 

P_U8 pWriteBuffer, // Destination of bytes to write 

P_U32 pCount // Out: Actual number of bytes written 

); 

♦define LVNWrite(pVolInfo, pVNode, filePos, numBytes, pWriteBuffer, pCount) \ 
( (pVolInfo) ->pRtns->pLVNodeWrite) \ 

(pVolInfo, pVNode, filePos, numBytes, pWriteBuffer, pCount) 

LVNG^^ 

Returns the size of a file. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_GET_SIZE) { 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode of node to change size of 

P_FS_FILE_SIZE pSize // The size of the file 

); 

#define LVNGetSize(pVolInfo, pVNode, pSize) \ 
{ (pVolInfo) ->pRtns->pLVNodeGetSize) \ 
(pVolInfo, pVNode, pSize) 
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Adjusts the size of a file. 
Returns STATUS. 



r-iincfiofi rrc 



typedef STATUS FunctionPtr (P_LVNODE_SET_SIZE) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode, // VNode of node to change size of 

FS_FILE_SIZE newSize // The new size 
); 
#define LVNSetSize(pVolInfo, pVNode, newSize) \ 

( (pVolInfo) ->pRtns->pLVNodeSetSize) \ 
(pVolInfo, pVNode, newSize) 

Flushes a file. 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LVNODE_FLUSH) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_VOLGODIR_VNODE pVNode // VNode of node to flush 
); 
#define LVNFlush(pVolInfo, pVNode) \ 

( (pVolInf o) ->pRtns->pLVNodeFlush) \ 
(pVolInfo, pVNode) 

LVNativeName 

Returns the native file system form of this name. 
Returns BOOLEAN. 

typedef BOOLEAN FunctionPtr (P_LV_NATIVE_NAME) ( 

P_VOLGODIR_INFO pVolInfo, // Vol Info 

P_STRING pName // In/Out: Name 

); 
tdefine LVNativeName (pVol Info, pName) \ 

( (pVolInf o) ->pRtns->pLVNativeName) \ 
(pVolInfo, pName) 

A return of true implies that the name v^as not changed {wsls native), and a return of false implies that 
the name w^as changed to be native. 



LDirldGetParent 

Gets the dir id of the parent of a node (also identified by dir id). 
Returns STATUS. 

typedef STATUS FunctionPtr (P_LDIRID_GET_PARENT) { 
P_VOLGODIR_INFO pVolInfo, // Vol Info 
U32 node, // Node identified by dir id 

P_U32 pParent, // In/Out: dir id of parent 

P_BOOLEAN pParentlsRoot // In/Out: parent is root 

); 

tdefine LDirldGetParent (pVolInfo, node, pParent, pParentlsRoot) \ 
( (pVolInfo) ->pRtns->pLDirIdGetParent) \ 

(pVolInfo, node, pParent, pParentlsRoot) 
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This is the definition for the table of volume routines 



typedef struct VOLGODIR_RTNS { 

P_LVOL_STATUS 

P_LVOL_SET_VOL_NAME 

P_LVOL_UPDATE_INFO 

P_LVOL_SPEC IF IC_MSG 

P_LVNODE_GET 

P_LVNODE_GET_OPEN_PARENT 

P_LVNODE_GET_OPEN_BY_DIR_ID 

P_LVNODE_RELEASE 

P_LVNODE_OPEN 

P_LVNODE_CLOSE 

P_LVNODE_CREATE 

P_LVNODE_DELETE 

P_LVNODE_MOVE 

P_LVNODE_READ_D IR 

P_LVNODE_DIR_POS_DEL_ADJUST 

P_LVNODE_GET_DIR_ID 

P_LVNODE_NAME 

P_LVNODE_GET_NUM_ATTRS 

P_LVNODE_GET_ATTR_INFO 

P_LVNODE_SET_ATTR_INFO 

P_LVNODE_READ 

P_LVNODE_WRITE 

P_LVNODE_GET_S I ZE 

P_LVNODE_SET_SIZE 

P_LVNODE_FLUSH 

P_LV_NATIVE_NAME 

P_LDIRID_GET_PARENT 
} VOLGODIR RTNS, *P VOLGODIR RTNS; 



pLVolStatus; 

pLVolSetVolName ; 

pLVolUpdateInf o ; 

pLVolSpecificMsg; 

pLVNodeGet ; 

pLVNodeGetAndOpenParent ; 

pLVNodeGetAndOpenByDirld; 

pLVNodeRelease ; 

pLVNodeOpen; 

pLVNodeClose; 

pLVNodeCreat e ; 

pLVNodeDelete; 

pLVNodeMove; 

pLVNodeReadDir; 

pLVNodeDirPosDelAd just ; 

pLVNodeGetDirld; 

pLVNodeName; 

pLVNodeGetNumAttrs ; 

pLVNodeGetAttrlnfo; 

pLVNodeSetAttrlnfo; 

pLVNodeRead; 

pLVNodeWrite; 

pLVNodeGetSize; 

pLVNodeSetSize; 

pLVNodeFlush; 

pLVNat i veName ; 

pLDirldGetParent ; 
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This file contains the API for clsVolSearch. 

clsVolSearch inherits from clsObject. 

Provides file system ui support, including formatting & duplicating disks. theVolSearcher is the only 
instance of clsVolSearch. 

The categories of functionality provided by theVolSearcher are: 

- Reformatting/duplicating a volume: 

These are sent from the disk viewer when a user selects the format or duplicate volume items from the 
volume menu. The user is lead thru a series of system notes to get the information and for disk 
swapping. 

- Searching for a volume (because it doesn't exist or is write protected): 

This is sent from the file system when a file system request internally returns a stsFSVolDisconnected or 
stsFSVolReadOnly. 

#ifndef VSEARCH_INCLUDED 
♦define VSEARCH_INCLUDED 

Include file dependencies 

tifndef GO_INCLUDED 
#include <go.h> 
#endif 

#ifndef OSTYPES_INCLUDED 
♦include <ostypes.h> 
tendif 

#ifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

#endif 

#ifndef FS_INCLUDED 

tinclude <fs.h> 

#endif 



Common #defines and typedefs 



These defines and enums define the text for the notes displayed by the volSearcher. The resources are 
stored in the system resource file. 

Defines 

Resource ids 

#define vsResUIStrings MakeTag (clsVolSearch, 1) 
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Types 




Resource string numbers 




Enuml 6 ( VS_STRING_IDS ) { 




vsFindVolumeStrsBase 


= 0, 


vsFindGenVolumeStr 


= 0, 


vsFindDiskVolumeStr 


= 1, 


vsFindRemoteVolumeSt r 


= 2, 


vsWriteProtectedVolumeStr 


= 3, 


vsCancelButtonStr 


= 4, 


vsContinueButtonStr 


= 5, 


vsPercentDoneStr 


= 6-, 


vsFmtNoticeStr 


= 7, 


vsFmtChooseSizeStr 


= 8, 


vsFmtWarningStr 


= 9, 


vsFmtAskForNameStr 


= 10, 


vsFmtBlankNameErrStr 


= 11, 


vsFmtBadCharErrStr 


= 12, 


vsFmtlnProgressStr 


= 13, 


vsDup InP rogre s s S t r 


= 14, 


vsDupInsertSrcDiskStr 


= 15, 


vsDupInsertDstDiskStr 


= 16, 


vsDupWriteProtectedStr 


= 17, 


vsDupReadingStr 


= 18, 


vsDupWritingStr 


= 19, 


vsFormattingMediaStr 


= 20, 



}; 

Messages 



msgVSFormatVolume 

Reformats an existing volume. 

Takes P_VS_FORMAT_VOLUME, returns STATUS. 

typedef struct VOL_FORMAT_VOLUME { 

OBJECT volumeRootDir; // Root dir of volume to format 

CHAR pVolumeName [nameBuf Length] ; // Suggested or actual name 

U16 reserved: 13, // Reserved 

noWarning:l, //Do not warn about dangers 

maxSize:l, // Format to maximum possible size 

withNamerl; // Name forced to be pVolumeName 

U32 reservedl; 

U32 reserved2; 

} VOL_FORMAT_VOLUME, * P_VOL_FORMAT_VOLUME ; 

#define msgVSFormatVolume MakeMsg(clsVolSearch, 5) 

The volumeRootDir must be the actual root of the volume to be formatted and there cannot be any- 
other handles open on the volume or an error will be returned. pVolumeName will be the initial name 
when the user is asked to provide a name or will be the name if the user is not asked to provide a name 
(controlled by the withName flag). The warning message can be controlled with the noWarning flag. 
And the choose a size interaction can be controlled with the maxSize flag. 

stsRequestNotSupported The volume does not support formatting. 
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Messages 



msgVSDuplicateVolume 

Copy an existing volume from one floppy disk to another floppy disk. 
Takes dir/file handle of a volume, returns STATUS. 

#define msgVSDuplicateVolume MakeMsg{clsVolSearch, 6) 

Return Valsie stsRequestNotSupported The volume does not support duplicating. 

msgVSFormatMedia 

Formats unformatted media that does belong to any volume. 

Takes block device object, returns STATUS. 

tdefine msgVSFormatMedia MakeMsg{clsVolSearch, 7) 

Comments This message is sent by theBlockDeviceManager when it receives a block device reset all and in the 

process discovers unformatted media on a device. 



msgVSUpdateVolumes 

Requests theVolSearcher to update all volumes. 

Takes BOOLEAN, returns STATUS. 

tdefine msgVSUpdateVolumes MakeMsg{clsVolSearch, 8) 

Comments This message requests the volSearcher to ask all volume classes to update their list of volumes. This may 

result in volumes being installed, removed, connected or disconnected. Interested parties should become 
observers of theFileSystem and look for msgFSVolChanged (see fs.h). The argument passed should be 
true to update all volumes. 

This message can only be sent via ObjectSendXXX. 

msgVSFormatCompleteNotify 

Notifies observers of theVolSearcher that a format has completed. 

Takes BOOLEAN, returns STATUS. 

#define msgVSFormatCompleteNotify MakeMsg(clsVolSearch, 20) 

Comments The argument passed to the observer indicates whether the format was successful or not. False would be 

returned if there was an error or if the format was cancelled. 

msgVSNameVolume 

Prompts user to name an unlabelled volume and adds new name. 

Takes root dir handle of volume, returns STATUS. 

tdefine msgVSNameVolume MakeMsg(clsVolSearch, 9) 

Comments This message is used by volumes that have discovered unlabeled volumes. This message can only be sent 

via Objecd^ostXXX. 
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CjyiPSTEXT.H 



This file contains tlie API definition for the compose-text package. 

This package is used to compose a text string that needs to have pieces inserted into it. The format of 
the strings makes it easy to internationalize and localize the text. 

The functions described in this file are contained in SYSUTIL.LIB. 

Format Strings 

The format strings contain literal text and format codes. A format code starts with '^', has a sequence of 
one or more digits in the middle, and a single letter at the end. The digits specify which argument to the 
function to use and the letter indicates the type of the argument. For instance, format code "^2s" 
indicates that the second argument should be inserted, and that the argument should be a string. 

The following fills 'buffer' with the string "a B b A c": 

SComposeText (&buffer, &size, heap, "a '^2s b ^Is c", "A", "B"); 
The available argument types are: 

^: Literal ''^' character. E.g. use "^^" to put a ^ in a string. 

s: String. 

r: Resource ID of a string resource. 

1: Group number and indexed list resource ID for string list. This uses two arguments. 

d: U32 printed as a decimal number. 

x: U32 printed as a hexadecimal number. 

{: Singular/Plural word forms of the form "{islare}". When this argument type is used, the routine 
examines the specified argument. If its value is 1, the first string is used. Otherwise the second string 
is used. 

The following code reads in a string from the TK group for a 'sample' project. 

SComposeText (&buffer, &size, heap, 

"The filled in string is ''11.", resGrpTK, sampleListResId) ; 

As an example of the '{' format code, the following code generates the first string if nuniApples==l and 
the second string if numApples==5. 

SComposeText (&buffer, &size, heap, 

"There ^1 {islare} ^Id ^1 {apple | apples} . ", numApples); 

"There is 1 apple." 
"There are 5 apples." 



Memory Management 



All of the procedures fill in a buffer with the generated string. There are two ways of supplying the 
buffer memory. 

♦ You can supply a buffer pointer and buffer length. Do this by passing the pointer as *ppString, the 
length in *pLength, and a null heapld. If this technique is used, and the buffer is too small to hold 
the results, an error status is returned. 



122 PENPOINT API REFERENCE 

Part 8 / System Services 

♦ You can specify a heap from which memory will be allocated. Do this by passing in a valid heapld. 
You are obligated to free the memory when finished. 

#ifndef CMPSTEXT_INCLUDED 

♦define CMPSTEXT_INCLUDED 

#ifndef GO_INCLUDED 

tinclude <go.h> 

tendif 

tifndef RESFILE_INCLUDED 

tinclude <resfile.h> 

tendif 

tinclude <stdarg.h> 

Common #clefines and Typedefs 

tdefine ComposeTextMaxArguments 20 // Maximum number of parameters 

P' Functions 

SComposeText 

Composes a string from a format and arguments. 

Returns STATUS. 

Fyocflon Prototype STATUS CDECL SComposeText ( 

PP_CHAR ppString, 
P_U32 pLength, 
OS_HEAP_ID heap, 
const P_CHAR pFormat, 

); 

Comnieiits Copy the format argument into the output string, doing the appropriate substitutions for the format 

codes. 

See the section "Memory Management" for information on what values to use for the first three 
arguments. 

VSComposeText 

Composes a string from a format and a pointer to the argument list. 

Returns STATUS. 

Function Prototype STATUS CDECL VSComposeText ( 

PP_CHAR ppString, 

P_U32 pLength, 

OS_HEAP_ID heap, 

const P_CHAR pFormat, 

va_list argList 
) ; 

Comments This is the same as SComposeText except the arguments are passed as a pointer to a list. 

See the section "Memory Management" for information on what values to use for the first three 
arguments. 






GOMATH.H 



This file contains the API definition for fixed point arithmetic. The fiinctions described in this file are 
contained in PENPOINT.LIB. 

The API in this file is all fiinction oriented, 

tifndef GOMATH_INCLUDED 
tdefine GOMATH_INCLUDED 

tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 



Math Operation Error Codes 



tdefine 
tdefine 
tdefine 
#define 
tdefine 
tdefine 
tdefine 
tdefine 
// The 
tdefine 
tdefine 



stsUnderflow 

stsOverflow 

stsMathlnvOp 

stsMathlnvStrOp 

stsMathEqual 

stsMathFirstHigher 

stsMathFirstLower 

stsZeroDivide 



MakeStatus (clsGOMath, 1) 

MakeStatus(clsGOMat]l, 2) 

MakeStatus (clsGOMath, 3) 

MakeStatus (clsGOMath, 4) 

MakeStatus (clsGOMath, 5) 

MakeStatus (clsGOMath, 6) 

MakeStatus (clsGOMath, 7) 

MakeStatus (ClsGOMath, 8) 
following two values are used by the runtime. lib as ERRNO values 

stsMathDomain MakeStatus (clsGOMath, 9) // Argument too large 

stsMathRange MakeStatus (clsGOMath, 10) // Result too large 



Math Constants 



tdefine GoFxO ((FIXED) 0x00000000) // 0.0 
tdefine GoFxl ((FIXED) 0x00010000) // 1.0 
tdefine GoFxMinusl ((FIXED) OxffffOOOO) // -1.0 



Fixed-point Function Prototypes 



FxCmp 



Compares two FIXED. 
Returns SI 6. 

S16 PASCAL FxCmp (FIXED a, FIXED b) ; 
-1 ifa<b. 

ifa = b. 

1 ifa>b. 
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FxAdd 

Adds two FIXED numbers, producing a FIXED. 
Returns STATUS. 

mtfmn Pmtotfpe STATUS PASCAL FxAdd (FIXED a, FIXED b, P_FIXED pC) ; 

stum¥0iMe stsOvcrflow The integer part of the result Overflows a 1 6-bit signed. 

Macro form of FxAdd with no overflow detection. 

Returns FIXED. 

#define FxAddSC(_fl,_f2) ( (FIXED) ( (_fl) + (_f2))) 

FxSub 

Subtracts two FIXED numbers, producing a FIXED. 

Returns STATUS. 
FoRcfiori Prototype STATUS PASCAL FxSub (FIXED a, FIXED b, P_FIXED pC) ; 
Return ¥«loe stsOverflow The integer part of the result overflows a 16-bit signed. 

FxSubSC 

Macro form of FxSub with no overflow detection. 

Returns FIXED. 

tdefine FxSubSC( fl, f2) ( (FIXED) ( ( fl) - ( f2))) 



FxNegate 

Negates a FIXED. 

Returns FIXED. 

#def ine FxNegate (_f ) ( (FIXED) (- (_f ) ) ) 



FxMul 

Multiplies two FIXED numbers, producing a FIXED. 

Returns STATUS. 
Function Pmfotype STATUS PASCAL FxMul (FIXED a, FIXED b, P_FIXED pC) ; 
Return Vcslye StsOverflow The integer part of the result overflows a 16-bit signed. 

Multiplies two FIXED numbers returning the product. 
Returns FIXED. 

F«r?cfion Prototype FIXED PASCAL FxMulSC (FIXED a, FIXED b) ; 
Comjiiertts No overflow detection is performed. 



storri Value 
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Fixed-point Function Prototypes 

FxMulInt 

Multiplies a FIXED number by an S32, producing a FIXED. 

Returns STATUS. !2 

STATUS PASCAL FxMulInt (FIXED a, 832 b, P_FIXED pC) ; « 

stsOverflow The integer part of the result overflows a 16-bit signed. 



FxMulIntSC 

Multiplies a FIXED number by an S32, returning the FIXED product. 
Returns FIXED. 

♦define FxMulIntSC (_a,_b) ( (FIXED) (_a*_b) ) 
Comments No overflow detection is performed. 

FxMulIniToInt 

Multiplies a FIXED number by an S32, producing a rounded S32 product. 
Returns STATUS. 

Fyntfion Prototype STATUS PASCAL FxMulIntToInt (FIXED a, S32 b, P_S32 pC) ; 

letyrn Voiye stsOverflow The integer part of the result overflows a 32-bit signed. 

Multiplies a FIXED number by an S32, returning a rounded S32 product. 
Returns S32. 

Foriction Prototype S32 PASCAL FxMulIntToIntSC (FIXED a, S32 b) ; 
Comments No overflow detection is performed. 

FxDiv 

Divides two FIXED numbers, producing a FIXED quotient. 
Returns STATUS. 

Foncfiofi Prototyise STATUS PASCAL FxDiv (FIXED top, FIXED bottom, P_FIXED pC) ; 
ieturri Vciliie stsOverflow The integer part of the result overflows a 16-bit signed. 

stsZeroDivide The input divisor is zero. 



FxDivSC 

Divides two FIXED numbers, returning a FIXED quotient. 

Returns FIXED. 

FIXED PASCAL FxDivSC (FIXED top, FIXED bottom); 

No overflow or zero-divide detection is performed. 
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FxDivInts 

Divides two 32-bit signed integers, producing a FIXED quotient. 
Returns STATUS. 

mcfiori Profofyi^e STATUS PASCAL FxDivInts (S32 top, S32 bottom, P_FIXED pC) ; 
styrri ¥oioe stsOvcrflow The integer part of the result overflows a 16-bit signed. 

stsZeroDivide The input divisor is zero. 

FxbivIntsSC 

Divides two FIXED numbers, returning a FIXED quotient. 
Returns FIXED. 

FIXED PASCAL FxDivIntsSC (S32 top, S32 bottom); 
No overflow or zero-divide detection is performed. 

F^DivintfoInt 

Divides an S32 by a FIXED, producing a rounded S32 quotient. 

Returns STATUS. 
Fujicfleii Prototype STATUS PASCAL FxDivIntToInt (S32 top, FIXED bottom, P_S32 pC) ; 
Sefyrri ¥akm stsOvcrflow The integer part of the result overflows a 16-bit signed. 

StsZeroDivide The input divisor is zero. 

Divides an S32 by a FIXED, producing a rounded S32 quotient. 
Returns S32. 
rpe S32 PASCAL FxDivIntToIntSC (S32 top, FIXED bottom); 
No overflow or zero-divide detection is performed. 






FxSin 

Returns the sine of an integer angle in degrees. 
Returns FIXED. 

•?Hv, p«=?on«3»-^ FIXED PASCAL FxSin (SI 6 angle); 

FxCos 

Returns the cosine of an integer angle in degrees. 
Returns FIXED. 

lion Prototype FIXED PASCAL FxCos (S16 angle) ; 
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Fixed-point Function Prototypes 



FxTan 

Returns the tangent of an integer angle in degrees. 



Returns FIXED. J2 

u 

Foficfioti Prototype FIXED PASCAL FxTan {S16 angle); ei 



FxSinFx 

>- 

Returns the sine of a FIXED angle in degrees. 
Returns FIXED. 

Foncfion Prototype FIXED PASCAL FxSinFx (FIXED angle); 

FxCosFx 

Returns the cosine of a FIXED angle in degrees. 
Returns FIXED. 

mcf'mn Pmtotype FIXED PASCAL FxCosFx (FIXED angle); 

FxTanFx 

Returns the tangent of a FIXED angle in degrees. 
Returns FIXED. 

Fyncfioo Prototype FIXED PASCAL FxTanFx (FIXED angle); 



FxArcTanInt 

Returns an arctangent value as a FIXED angle. 
Returns FIXED. 

mcf'mn Prototype FIXED PASCAL FxArcTanInt (S32 top, S32 bottom) ; 

smments Computes a FIXED angle whose tangent is the value given by the quotient of the two signed 32-bit 

integers, top / bottom. The value returned ranges from to 359 degrees. 

FxArcTanFx 

Returns an arctangent value as a FIXED angle. 
Returns FIXED. 

incfion Prototype FIXED PASCAL FxArcTanFx (S32 top, S32 bottom); 

smments Computes a FIXED angle whose tangent is the value given by the quotient of the two signed 32-bit 

numbers, top / bottom. The value returned ranges from to 359 degrees. 

FxAbs 

Takes the absolute value of a FIXED. 

Returns FIXED. 

#define FxAbs ( f ) ( ( ( f ) <0) ?FxNegate (_f ) : (_f ) ) 
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FxRoundToInt 

Rounds a FIXED number to a 32-bit signed integer. 

Returns S32. 

S32 PASCAL FxRoundToInt (FIXED fx) ; 

FxRoundToIntSC 

Rounds a FIXED number to a 16-bit signed integer. 
Returns SI 6. 

tdefine FxRoundToIntSC {_f ) (S16) ( ( (_f ) +0x8000) »16) 
No overflow detection is performed. 



FxChop 

Returns the 16-bit signed integer part of a FIXED. 
Returns SI 6. 

#define FxChop (_f) (S16) ( (_f)»16) 
tdefine FxChopSC(_f) (S16) ( (_f )»16) 

FxFraction 

Returns the 16-bit fractional part of the absolute value a FIXED. 

Returns U16. 

#define FxFraction ( f) (U16)(FxAbs( f ) ) 



FxIn^ToFx 

Converts a 1 6-bit signed integer into a FIXED. 

Returns FIXED. 

#define FxIntToFx(_i) ( (FIXED) ( ( (S32) (_i) )«16) ) 

FxMakeFixed 

Makes a FIXED with an S16 (integer) and a Ul 16 (fraction). 

Returns FIXED. 

FIXED PASCAL FxMakeFixed(Sl6 whole, U16 frac); (now in go.h) 

FxBinToStr 

Converts a FIXED format value into an ascii string in decimal. 

Returns nothing. 

void PASCAL FxBinToStr ( 
FIXED a, 
P_CHAR pStr, 
U8 fracDigits, 

US maxLen, 

BOOLEAN showCommas 
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Fixed-point Function Prototypes 



Commesits The String will have the format: 

{-jxxxxx.xxxxx or {-}xx,xxx.xxxxx. 

The number of digits to the lefi; of the decimal point is the minimum number required, and the number 
of digits to the right of the decimal point is specified in fracDigits. The last digit is rounded accurately. 
If the string will not fit within maxLen bytes, then the string "*******" (maxLen-1 *'s) will be returned; 
maxLen = 9+fracDigits is sufficient, although any higher number is also acceptable. If showCommas is 
true, then commas will separate the thousands. 

FxStrToBin 

Converts a null-terminated ascii string to a FIXED. 

Returns STATUS. 

Fonctlorj Pr0f©fype STATUS PASCAL FxStrToBin ( 
P_CHAR pStr, 
P_FIXED pC 
); 

Commertts The fractional portion will be rounded to fit within 16 bits. 

iefym Value stsOverflow The integer part of the result overflows a 16-bit signed. 

stsMathlnvStrOp A character in the string does not represent a valid number. *pC is set to zero. 
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INTL.H 



Definitions used while internationalizing code. 

The main content of this fde is macros that map the names of UNICODE string flinctions for 
PENPOINT 2.0 to the 8-bit flinctions used currently. They are intended to be used with items of type 
CHAR, which are 8-bit currently and will switch to 16-bit in 2.0. By using these macros code that deals 
with strings will have a chance of working in 2.0 with only a recompile. 

tifndef INTL_INCLUDED 
♦define INTL INCLUDED 



UNICODE strings/characters 



To define characters or strings in PENPOINT 1.0, use the "U_L" macro on them. This maps to the 
original string, and thus does nothing. In 2.0 the define will be changed so that it inserts "L" in front of 
the string. This will convert the character or string into a wide character or string to match the 2.0 
definition of CHAR. 

Here is some sample code to show its use. This code would compile and run under both 1.0 and 2.0, the 
only difference would be the space allocated for each character (1 vs. 2 bytes). 

CHAR cc; 
P_CHAR pString; 

pString = U_L(" sample string"); 
cc = U_L('s') ; 

if (cc == pString [0]) 

pString[0] = U_L('S'); 
♦define U_L(str) str // Does nothing in PENPOINT 1.0 
// #define U_L{str) L##str // Definition to be used in PENPOINT 2.0 



Mapping of 16-bit string/character 
functions for 1.0 



For each of the sections below, it is necessary to include the base header file in order to use the macros 
defined here. 

These macros are intended to be used with variables of type CHAR. CHAR is currently U8, and will be 
converted to U16 in PENPOINT 2.0. 
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Extensions to STRING.H 



tdefine Ustrcat 


strcat 


tdefine Ustrncat 


strncat 


tdefine Ustrcmp 


strcmp 


tdefine Ustrncmp 


strncmp 


tdefine Ustrcpy 


strcpy 


tdefine Ustrncpy 


strncpy 


tdefine Ustrlen 


strlen 


tdefine Ustrdup 


strdup 


tdefine Ustrrev 


strrev 


tdefine Ustrset 


strset 


tdefine Ustrnset 


strnset 


tdefine Ustrchr 


strchr 


tdefine Ustrrchr 


strrchr 


tdefine Ustrspn 


strspn 


tdefine Ustrcspn 


strcspn 


tdefine Ustrpbrk 


strpbrk 


tdefine Ustrstr 


strstr 


tdefine Ustrtok 


strtok 


tdefine Ustricmp 


stricmp 


strcmpi' the same as 


'stricmp, we do 


tdefine Ustrnicmp 


strnicmp 


tdefine Ustrlwr 


strlwr 


tdefine Ustrupr 


strupr 


tdefine Umemcpy 


memcpy 


tdefine Umemccpy 


memccpy 


tdefine Umemchr 


memchr 


tdefine Umemcmp 


memcmp 


tdefine Umemicmp 


memicmp 


tdefine Umemmove 


memmove 


tdefine Umemset 


memset 


tdefine Ustrerror 


strerror 



Extensions to CTYPE.H 



tdefine Uisalpha 


isalpha 


tdefine Uisalnum 


isalnum 


tdefine Uisascii 


isascii 


tdefine Uiscntrl 


iscntrl 


tdefine Uisprint 


isprint 


tdefine Uisgraph 


is graph 


tdefine Uisdigit 


isdigit 


tdefine Uisxdigit 


isxdigit 


tdefine Uislower 


islower 


tdefine Uisupper 


isupper 


tdefine Uisspace 


is space 


tdefine Uispunct 


ispunct 


tdefine Utolower 


tolower 


tdefine Utoupper 


toupper 



Extensions to STDLIB.H 



tdefine Uatoi 


atoi 


tdefine Uatol 


atol 


tdefine Uitoa 


itoa 


tdefine Ultoa 


Itoa 


tdefine Uutoa 


utoa 


tdefine Ustrtol 


strtol 


tdefine Uatof 


atof 


tdefine Ustrtod 


strtod 


tdefine Ustrtoul 


strtoul 



INTL.H 
Mapping of 16-bit string/character functions for 1.0 
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This goes directly to its 2.0 definition because it does not make sense on an ascii text stream, and if ttie 
current text is not ascii, then having it automatically convert to Unicode by recompile in 2.0 won't 
work. It is included mostly to reserve the name, and let programers know that it will be available. 

#define Uswab(s,d,n) swab ((char *)s, (char *)d, n*2) 



Extensions to STDIO.H 



♦define Ufopen 


fopen 


♦define Usprintf 


sprint f 


♦define Uvsprintf 


vsprintf 


♦define Usscanf 


sscanf 


♦define Uputc 


putc 


♦define Ufputc 


fputc 


♦define Ugetc 


getc 


♦define Ufgetc 


fgetc 


♦define Uungetc 


ungetc 


♦define Ufdopen 


fdopen 


♦define Ufreopen 


freopen 


♦define Uprintf 


print f 


♦define Ufprintf 


fprintf 


♦define Uvprintf 


vprintf 


♦define Uvfprintf 


vfprintf 


♦define Uscanf 


scanf 


♦define Ufscanf 


fscanf 


♦define Uvscanf 


vscanf 


♦define Uvfscanf 


vfscanf 


♦define Uvsscanf 


vsscanf 


♦define Ugetchar 


get char 


♦define Uf get char 


fgetchar 


♦define Ugets 


gets 


♦define Ufgets 


fgets 


♦define Uputchar 


put char 


♦define Ufputchar 


fputchar 


♦define Uputs 


puts 


♦define Ufputs 


fputs 


♦define Uremove 


remove 


♦define Urename 


rename 


♦define Utmpnam 


tmpnam 



Extensions to FCNTLH 



♦define Uopen 
♦define Usopen 
♦define Ucreat 



open 

sopen 

creat 



Extensions to TIME.H 



♦define Uasctime asctime 
♦define Uctime ctime 



Extensions to UNISTD.H 

♦define Urmdir rmdir 

♦define Uchdir chdir 

♦define Ugetcwd getcwd 



Extensions to DIRENT.H 

♦define Uopendir 
♦define Ureaddir 



opendir 
readdir 
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OS.H 



This file contains the API for the PenPoint kernel. The flinctions described in this file are contained in 
PENPOINT.LIB. 

The PenPoint kernel provides support for tasking, memory management, inter-task communication and 
timer services. 

tifndef OS_INCLUDED 
tdefine OS INCLUDED 



Debugging Flags 

PenPoint kernel flag is 'G', values are: 

0001 User configuration (copy exes from boot to theSelectedVolume) 

0002 Enter debugger on faults while scavenging 

0004 Display memory sizes for each module loaded and run 

0008 Display Stack grow/ shrink messages 

0010 Save page fault information in a memory buffer 

0020 Run in the Ram only configuration 

0100 Print various memmgr details 

1000 see resfile.h 

2000 see resfile.h 

4000 see resfile.h 

8000 see resfile.h 

10000 Internal use only 

20000 Call the MIL using the common entry point for fiiU debugging 

tifndef GO_INCLUDED 

tinclude <go.h> 

#endif 

tifndef OSTYPES_INCLUDED 

#include <ostypes.h> 

#endif 

tifndef OSHEAP_INCLUDED 

tinclude <osheap.h> 

#endif 

Common #defines and typedefs 

tdefine osPageSize (4*1024) 

Defines for OS_ITMSG_INFO (mode field) 

// To generate the mode, OR in OS_TASK_MODE with the defines below. 

tdefine osITMsgNoCopy flag7 // vs copy buffer 

♦define osITMsgFrontOfQ flag6 // vs end of queue 

tdefine osITMsgDefaultMode // Copy msg to end of msg queue 
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Defines for setting priority 



#define osNumPriorities 


51 




♦define osDefaultPriority 







♦ Defines for region information 




typedef U8 


OS REGION ATTRS; 


tdefine osRgnLocal 


flagO 




#define osRgnHasAliases 


flagl 




#define osRgnLocked 


flag2 


// Not yet implemented! ! 


tdefine osRgnNotSwappable 


flags 




tdefine osRgnFrozen 


flag4 


// Not yet implemented! ! 


tdefine osRgnlnSlowMem 


flags 




Enuml6(OS_REGI0N_TYPE) { 






osRgnData, 




// data region 


osRgnHeap, 




// heap region 


osRgnStack, 




// stack region 


osRgnMemMapFile, 




// memory mapped file region 


osRgnCode 




// code region 



}; 



Subtask fixnction type 



typedef void FunctionPtr (P_OS_SUBTASK_ENTRY) (U32 arg) ; 

Enuml6(0S_SET_GET) { 

osValuesSet = flagO, // Set the value (s) passed in 

osValuesReturn = flagl, // return the value (s) 

OS Value sReturnAndSet = flagO | flagl // return and set the value (s) 

}; 



Memory access attributes 



// 
// 
// 
// 
// 



access rights of a page 
page allows read access 



page 
page 
page 



Enuml6(0S_ACCESS) { 
osReadAccess, 
osReadWriteAccess, 
osExecuteAccess , 
osExecuteReadAccess 
}; 

Enumie (OS_SET_TIME_MODE) 
osSetTime = flagO, 
osSetDate = flagl, 
osSetTimeZone = flag2, 
osSetDateAndTime = osSetTimelosSetDate, 
// set date, time, and time zone 
osSetAll = osSetTimelosSetDate I osSetTimeZone 



{ 



allows 
allows 
allows 



// 
// 
// 
// 



only 
read and write access 
execute access only 
execute and read access 



set the time 

set the date 

set only the time zone 

set both the date and time 



}; 



Display modes 



Enuml 6 ( OS_D I SPLAY_MODE ) { 

osConsole, // display mode is console 
osGraphics // display mode is graphics 

}; 

♦ Beep error tones 

Enumie {OS_ERROR_TYPE) { 

osWarning, 

osFatal 
}; 
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♦ System wide memory information 

typedef struct OS_MEM_INFO { 
U32 taskMemAllocated; 
U32 localTaskMemAllocated; 
U16 nuinAllocatedRgns; 
U16 numAllocatedLocalRgns; 
U32 taskMemResident; 
U32 taskMemSwapped; 
// system wide statistics 
U32 systemRamSize; 
U32 amtlnMemoryPool; 
U32 meniFree; 
U32 memAllocated; 
U16 numRgnsAllocated; 
U16 numSharedRgnsAllocated; 
U32 pageSize; 
// swap file statistics 
U32 memNotSwappable; 
U32 swapFileSize; 
U32 swapMediaFreePages; 



// amt of mem allocated by the task 

// amt of local mem allocated by the task 

// # allocated regions by the task 

// # local regions allocated 

// amt of allocated mem in ram-this task 

// amt of allocated mem in swap file-this task 

// total amt of memory in the system 

// amt of memory in the memory pool 

// amt of free ram 

// total amt of mem allocated by all 

// total # regions allocated by all 

// # shared regions used by all 

// system page size 

// amt of memory not swappable 

// size of the swap file 

// number of pages free on the swap media 



// system wide allocated memory statistics (currently in ram) 



U32 dataAllocated; 
U32 heapsAllocated; 
U32 stacksAllocated; 
U32 memMapFilesAllocated; 
U32 codeAllocated; 
} OS_MEM_INFO, * P_OS_MEM_INFO; 

♦ Memory usage information 



// amt of data allocated 

// amt of heap space allocated 

// amt of stack space allocated 

// amt of mem map file space allocated 

// amt of code space allocated 



// Region info, per type of region (code, data, etc) 
typedef struct OS REGTYPE INFO { 



U32 
U32 
U32 
U32 
} OS REGTYPE INFO, 



allocated; 
swappable ; 
nonswappable; 
committed; 
*P_OS_REGTYPE_INFO ; 

// Region info, per scope of region (local, shared, etc) 
typedef struct OS REGSCOPE INFO { 



// Max size of the region 

// swappable pages in memory 

// non- swappable pages in memory 

// committed pages 



OS_REGTYPE_INFO 
OS_REGTYPE_INFO 
OS_REGTYPE_INFO 
OS_REGTYPE_INFO 
OS_REGTYPE_INFO 
} OS REGSCOPE INFO, 



code; 
data; 
heap; 
stack; 
memMapFile; 
*P OS REGSCOPE INFO; 



// Executable code 

// Data 

// Data used as heaps 

// Stack space 

// Memory-mapped files 



typedef struct OS MEM USE INFO { 



OS_REGSCOPE_INFO 

OS_REGSCOPE_INFO 

OS_REGSCOPE_INFO 

OS_REGSCOPE_INFO 

U32 

U32 

U32 

U32 

U32 



local; 

shared; 

multiOwner; 

total; 

pageSize; 

SystemRamSize; 

memFree; 

memAllocated; 

swapFileSize; 



// Owned by this task only, in local memory 

// Owned by this task only, in shared memory 

// Owned by this task and at least one other 

// System-wide totals 

// System page size 

// total amt of memory in the system 

// mem in the "free" list 

// mem not in the "free" list 

// size of the swap file 



} OS MEM USE INFO, *P OS MEM USE INFO; 
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♦ Address information 



typedef struct OS_ADDRESS_INFO { 

P_MEM pRegionBase; 

SIZEOF regionLength; 

OS_ACCESS access; 

OS_TASK_ID owner; 

BOOLEAN userPriv; 

OS_REGION_ATTRS flags; 

SIZEOF residentSize; 

SIZEOF committedSize; 

OS_REGION_TYPE regionType; 
} OS ADDRESS INFO, * P OS ADDRESS INFO; 



// Info for a given memory address 

// base of region 

// length of the region 

// access rights of the region 

// owning task for this region 

// TRUE - user region, FALSE - kernel 

// see defines above 

// amount of region that is resident 

// amount of region that is committed 

// type of region 



System configuration information 



typedef struct OS_SYSTEM_INFO { // system configuration information 
BOOLEAN mathProcessorPresent; // TRUE = present 
OS_MILLISECONDS millisecondsPerSystick; // ms per clock tick 

} OS_SYSTEM_INFO, * P_OS_SYSTEM_INFO; 

♦ Date and time information 

// The time zone string is a POSIX format string. See the Watcom library 

// reference for PenPoint, TZ environment variable set section for more info, 

typedef struct OS_DATE_TIME { 

seconds; // seconds after the minute — [0,61] 

minutes; // minutes after the hour — [0,59] 

hours; // hours after midnight — [0,23] 

day; // day of the month — [1,31] 

month; // months since January — [0,11] 
year; // years since 1900 

dayOfWeek; // days since Sunday — [0,6] 

dayOfYear; // days since January 1 — [0,365] 
pTimeZone; 



U32 
U32 
U32 
U32 
U32 
U32 
U32 
U32 

P_CHAR 
} OS DATE TIME, 



// time zone string (POSIX format) 



* P OS DATE TIME; 



♦ Loaded program information 

typedef struct OS_PROG_INFO { 

OS_PROG_HANDLE progHandle; // 

CHAR name [32+1]; // 

U32 initHeapSize; // 

U32 initStackSize; // 

U16 initCS; // 

U32 initIP; // 

U32 nRegions; // 

U16 initDS; // 

U16 isDLL :1, // 

isUser :1, // 

rsvd :14; // 

U32 fixedSize; // 

U32 sharedSize; // 

U32 privateSize; // 

U32 nRequiredModules; // 
} OS PROG INFO, * P OS PROG INFO; 



program identifying handle 
module name (without the .exe) 
.exe-header initial heap allocation 
.exe-header initial stack allocation 
initial CS (selector, not segment!) 
initial IP 

# of regions 
initial DS 

for .exes, 1 for DLLs 

1 for user priv, for system priv 
reserved for future use. 

read-only segments + initialization data 
shared read/write segments 
private read/write segments 

# modules this depends upon 



Interrupt information 



// Note: OR in the flag osIntNumlsHardwareLevel if intNum is a hardware 
// interrupt level (vs a MIL logical device id) . The flag is defined 
// in ostypes.h. 
typedef struct OS_INTERRUPT_INFO { 

OS_INTERRUPT_ID intNum; 

P_UNKNOWN pCode; 

} OS INTERRUPT INFO, * P OS INTERRUPT INFO; 



// struct used to set interrupts 

// logical interrupt id 

// ptr to interrupt routine 
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♦ Module entrypoint types 

Enuml6(0S_ENTRYP0INT_TYPE) { 
osEntryName, 
osEntryOrdinal 

}; 

♦ Message information 

typedef struct OS_ITMSG_INFO { 

OS_ITMSG_FILTER filter; 

P_MEM pITMsg 

SIZEOF length 

U32 token; 

OS_TASK_ID taskid; 

U16 mode; 

} OS_ITMSG_INFO; 

♦ Fast sema struct 

typedef struct OS_FAST_SEMA { 
U16 count; 

U16 nWaits; 

OS_TASK_ID owner; 
} OS FAST SEMA, *P OS FAST SEMA; 



// entrypoint is named 

// entrypoint is an ordinal 



// inter-task message information 

// filter of the message 

// pointer to inter-task message buffer 

// length of the message buffer 

// user defined info field 

// dest or sending task Id 

// see defines for OS ITMSG INFO 



// top bit for test and set 

// bits 0-14 for recursive counting 

// number of waiters 



Functions 



ion Protot^ 



turn Voii 



OSProgramlnstall 

Installs a program into the loader database. 
Returns STATUS. 

STATUS EXPORTEDO OSProgramlnstall ( 

P_CHAR pCommandLine, // die or exe name (and arguments) 

P_CHAR pWorkingDir, // working dir of the program 

P_OS_PROG_HANDLE pProgHandle, // Out: program handle 

P_CHAR pBadName, // Out: If error, dll/exe that was bad 

P_CHAR pBadRef // Out: If error, reference that was bad 

); 

If a die file is provided, all dlls in the file vvfill also be loaded if not loaded already. 

OSProgramlnstall will not return until instance of all loaded dlls and exe are completed. No message 
dispatching will occur during this time. If communication to the calling task is required, use 
IMProgramlnstall (install.h, install.lib). 

OSProgramDeinstall 

stsOSBadDLCFormat DLC file is incorrectly formatted 

stsOSBadExeFormat A DLL or EXE is invalid in the die file 

stsOSProglnstallError Use debug version of PenPoint for more info 

stsOSModuleNotFound Module name specified in die file is invalid 

stsOSMissingDependency Import module in an exe or dll was not found 

stsOSMisingEntryName Import name in an exe or dll was not found 

stsOSMissingEntryOrdinal Import number in an exe or dll was not found 
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OSProgramDeinstall 

Deinstalls a program already loaded into the loader database. 

Returns STATUS. 

Foncfiors Protefyp© STATUS EXPORTEDO OSProgramDeinstall ( 

OS_PROG_HANDLE progHandle // program handle 
); 

Comments This routine will terminate any dll task wrappers before deinstalling the code. If an exe is being 

deintalled, all tasks must be terminated before calling this routine. 

See Also OSProgramlnstall 

RetMrn ¥aloe stsOSInvalidProgramHandle Program handle is incorrect 

stsOSDependenciesExist Another program requires this dll or a task is using this module 

OSProgramlnstantiate 

Creates an instance of a program. 

Returns STATUS. 

fumt'mn Prototype STATUS EXPORTEDO OSProgramlnstantiate ( 

OS_PROG_HANDLE progHandle, // program handle from install 

P_CHAR pCommandLine, // pathname + arguments 

P_OS_TASK_ID pTaskId // Out: Task id of the new task 

); 

Comments The newly created process will be set to the same priority as the caller. 

Return Value stsBadParam Program handle is invalid 



OSSubTaskCreate 

Creates a new execution thread in this context. 

Returns STATUS. 

¥umfmn Prototype STATUS EXPORTEDO OSSubTaskCreate ( 

P_OS_SUBTASK_ENTRY pEntrypoint, // Function entrypoint 

SIZEOF stackSize, // ignored. 

U16 mustBeZero, // reserved 

U32 arg, // arg passed to function 

P_OS_TASK_ID pTaskId // Out: new task id 
); 

Comments The entrypoint that starts the subtask must NOT return. To terminate the task, use OSTaskTerminate 

(OSThisTask ()) as the last line in the routine. The newly created task will be set to the same priority as 
the caller. 

The initial stack size of the subtask will be set to 4096 bytes. The stackSize parameter will be ignored. 
Stacks will automatically grow to accomodate a program's stack requirements. 

OSTaskTerminate 

Terminates a task. 

Returns STATUS. 

F«ncti0n Prototype STATUS EXPORTEDO OSTaskTerminate ( 

OS_TASK_ID taskid, // task to terminate 

OS_TASK_ERROR exitCode // reason for terminating exit code 

); 
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Comments Callers to OSTaskTerminate will not return until the task has successfully terminated. Task termination 

will cause the following events to occur: 

1) if a process is terminated, all subtasks are first terminated 



«n 



2) observers of theProcess will be notified (see clsmgr.h). The error code is provided with the S 
notification. 2 

3) objects owned by the terminating task will be scavenged ^ 

4) a broadcast message will be sent to all tasks to notify them of the the task termination. The message ^ 
will be sent on the filter osTerminatedTaskFilter. This filter is by default off. 



OSNextTerminatedTaskId 

Notifies the caller of the tasks that have terminated. 

Returns the next task that has terminated. 

Function Prototype OS_TASK_ID EXPORTEDO OSNextTerminatedTaskId ( 

P_OS_TASK_ERROR pExitCode // Out: exit code of terminating task 

); 

Commerits The broadcast message for task termination does not include the task identifier of the task that has 

terminated. To find this out, this routine should be called to get the list of terminated tasks. When 
osNullTaskId is returned, the list ends. 

Passes back the task identifier of the current running task. 
Returns OS_TASK_ID. 

lion Prototype OS_TASK_ID EXPORTED OSThisTask (void) ; 

OSTaskPrioritySet 

Sets the priority of a task or a set of tasks. 

Returns STATUS. 

Fynction Prototype STATUS EXPORTEDO OSTaskPrioritySet ( 

OS_TASK_ID taskid, // target task 

OS_TASK_MODE mode, // task mode 

OS_PRIORITY_CLASS priorityClass, // new priority class 

U8 priority // new priority number 

); 
Comments The task mode can be used to set the priority of just one task or all tasks in the process family. 

See Also OSTaskPriorityGet 



OSTaskPriorityGet 

Passes back the priority of a task. 

Returns STATUS. 

tlon Prototype STATUS EXPORTEDO OSTaskPriorityGet ( 

OS_TASK_ID taskid, // target task 

P_OS_PRIORITY_CLASS pPriorityClass, // Out: task's priority class 
P_U8 pPriority // Out: task's priority number 

); 
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Comments Both the priority class and the priority within that class are returned. 

See Mso OSTaskPrioritySet 



OSTaskDelay 

Delays the current task for a specified period of time. 

Returns STATUS. 

funcfmn Prototype void EXPORTEDO OSTaskDelay ( 

OS_MILLISECONDS timeLimit // milliseconds to delay 
); 

Comments When the machine is turned off, the delay time freezes until the system is turned back on again. 

OSTaskDelay cannot be called from an interrupt subtask. 



OSITMsgSend 

Sends an inter-task message to a task or set of tasks. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO OSITMsgSend ( 

P_OS_ITMSG_INFO pITMsglnfo // inter-task message info block 

); 

Comments OSITMsgSend is used to send an inter- task message to 1) a single task, or 2) all tasks in a task family, or 

3) all tasks in the system. The combination of the taskid and mode fields are used to accomplish this. If 
broadcasting to all tasks, the taskid field is ignored. 

An inter-task message is an array of bytes completely uninterpreted by the kernel stored in the pITMsg 
field. If the inter- task message is short (up to U32), it can be stored in the token field for improved 
performance. The length field is used to store the length of the inter-task message in pITMsg. If the 
length field is 0, the pITMsg field is ignored and can be used for more information passing. 

Inter-task messages are passed to the destination task in two ways: copy and alias. In copy mode, the 
message is copied into a new buffer allocated in the context of the destination task. In alias mode, the 
message is aliased into the destination task. Messages must be full regions when using alias mode. 

Messages are normally inserted into the end of the destination message queue. However, it is possible to 
specify that a message be inserted into the front of the message queue. 

Inter- task messages will get delivered to tasks that have a filter mask set to allow messages of the sending 
messages filter. If sending a message on multiple filters, the message will be delivered if any one of the 
filters are allowed by the receiving task. No error status is returned if the receiving task does not receive 
the message due to its filter mask setting. 

See Also OSITMsgReceive 



OSITMsgReceive 

Receives a message from the task's message queue. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO OSITMsgReceive { 

P_OS_ITMSG_INFO pITMsglnfo, // In-Out: message info block 

OS_MILLISECONDS timeLimit // amount of time to wait for message 

); 
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Messages are received by specifying a filter or set of filters in the pITMsglnfo struct. Any message with a 
filter that is in that set will match the receive request. The filter in the pITMsglnfo struct must always 
be set on entry. 

When a message is received that matches the input filter, the message is removed from the queue and SS 

provided to the client. ^ 

111 

OSITMsgSend S 



OSITMsgPeek 

Gets the next message from the message queue without removing it. 

Returns STATUS. 

Fyncfiort Prototype STATUS EXPORTEDO OSITMsgPeek ( 

P_OS_ITMSG_INFO pITMsglnfo, // In-Out: message info block 

OS_MILLISECONDS time Limit, // amount of time to wait for message 

P_OS_ITMSG_ID pITMsgId // In-Out: id of message received 

); 

Comments *pITMsgId of null peeks from the front of the queue. Use the previous message id to peek fiirther into 

the queue. The filter in the pITMsglnfo struct must always be set on entry. 

See Also OSITMsgFromId 

OSITMsgFromld 

Passes back the message associated with the message identifier. 

Returns STATUS. 

FynctioR Prototype STATUS EXPORTEDO OSITMsgFromld ( 

P_OS_ITMSG_INFO pITMsglnfo, // In-Out: message info block 

OS_ITMSG_ID itMsgId // message id obtained from OSITMsgPeek 

); 

Comments The message identifier should be obtained by calling OSITMsgPeek. 

See Also OSITMsgPeek 



OSITMsgQFlush 

Flushes the message queue of all messages matching the message filter. 

Returns STATUS. 

Fynction Prototype STATUS EXPORTEDO OSITMsgQFlush ( 

OS_ITMSG_FILTER itMsgFilter // message filter of messages to flush 

); 

Comments If a message has other filters set in addition to itMsgFilter, then the message will NOT be flushed. 

Sets the filter mask for this task. 
Returns the old filter mask. 

Function Prototype OS_ITMSG_FILTER EXPORTEDO OSITMsgFilterMask ( 

OS_ITMSG_FILTER newITMsgFilter, // new filter mask for this task 
BOOLEAN setNewFilter // if true, the new filter mask will be set 
); 
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ments Setting the mask bit to 1 indicates the message is allowed by this task; otherwise. Any messages sent to 

this task whose filter bits are off in the filter mask will be discarded. 

If setNewFilter is FALSE, newITMsgPilter is ignored and only the old filter mask is returned. 

Ms© OSITMsgSend 

OSSemaCreate 

Creates a semaphore. 

Returns STATUS. 

STATUS EXPORTEDO OSSemaCreate ( 

P_OS_SEMA_ID pSema // Out: new open semaphore 

); 

The semaphore will automatically be opened for the process. 
OSSemaOpen 

OSSemaOpen 

Opens (accesses) an already existing semaphore. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO OSSemaOpen { 

OS_SEMA_ID sema, // semaphore 

OS_TASK_ID task // task wanting to share ownership of sema 

); 

Camineots Tasks should always open someone else's semaphore to guarantee that the semphore will be around even 

if the original owner of the semaphore terminates. 

Ses- #\i$0 OSSemaCreate 

OSSemaDelete 

Deletes a semaphore. 

Returns STATUS. 

¥umfmn Prototype STATUS EXPORTEDO OSSemaDelete ( 

OS_SEMA_ID sema // the semaphore to delete 

); 

ComtTsents The semaphore will be removed from the system when all owners of the semaphore have deleted it. 

See Also OSSemaCreate 



OSSemaRequest 

Locks the counting semaphore (increments the count). 
Returns STATUS. 

STATUS EXPORTEDO OSSemaRequest ( 

OS_SEMA_ID sema, // the semaphore to lock 

OS_MILLISEC0NDS timeLimit // max time to wait if already locked 

); 

OSSemaRequest should be used in conjunction with OSSemaClear when using semaphores to protect 
critical sections of code. OSSemaRequest/OSSemaClear implement a counting semaphore model which 
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allows nesting of OSSemaRequest calls. Only after the same number of OSSemaClear calls will the next 
waiting task enter the critical section. Up to 64K nestings are allowed. 

If a task has obtained a isemaphore via OSSemaRequest and subsequently dies, the semaphore will be 
given to the next requestor and that requestor will be given the status stsOSSemaLockBroken. 

Refyrn Value stsOSSemaLockBrokcn Previous locker of semaphore died without clearing the semaphore 

stsOSTimeOut The timelimit expired before obtaining the semaphore 

See Also OSSemaClear 

OSSemaClear 

Unlocks the counting semaphore (decrements the count). 

Returns STATUS. 

Fyncfion Prototype STATUS EXPORTEDO OSSemaClear ( 

OS_SEMA_ID sema // the semaphore to unlock 

); 

Comments OSSemaClear should be used in conjunction with OSSemaRequest when using semaphores to protect 

critical sections of code. OSSemaRequest/OSSemaClear implement a counting semaphore model which 
allows nesting of OSSemaRequest calls. Only after the same number of OSSemaClear calls will the next 
waiting task enter the critical section. Up to 64K nestings are allowed. 

See Also OSSemaRequest 



OSSemaReset 

Resets event semaphore (no matter what count). 

Returns STATUS. 

function Prototype STATUS EXPORTEDO OSSemaReset ( 

OS_SEMA_ID sema // the semaphore to reset 
); 

Comments OSSemaReset is used with OSSemaSet and OSSemaWait to support event handling. In this model, the 

client waiting on the event should use OSSemaSet to set the semaphore to 1, and OSSemaWait to wait 
until the semaphore has been reset to 0. OSSemaReset will reset the semaphore to 0, thereby notifying 
all tasks waiting on the event. OSSemaReset is normally used in interrupt tasks. The task that is 
processing the event may actually have received more than one event and should process all events after 
resetting the semaphore to avoid losing any events. 

See Also OSSemaSet 

OSSemaSet 

Sets the event semaphore to 1 . 

Returns STATUS. 

Fynctlon Prototype STATUS EXPORTEDO OSSemaSet ( 

OS_SEMA_ID sema // the semaphore to set 

); 

Comments OSSemaSet is used with OSSemaWait and OSSemaReset to support event handling. In this model, the 

client waiting on the event should use OSSemaSet to set the semaphore to 1 , and OSSemaWait to wait 
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until the semaphore has been reset to 0. OSSemaReset will reset the semaphore to 0, thereby notifying 
the task waiting on the event. 

OSSemaReset 



OSSemaWait 

Waits for the event semaphore to be reset. 

Returns STATUS. 

Funcflofi Prototype STATUS EXPORTEDO OSSemaWait ( 

OS_SEMA_ID sema, // the semaphore to wait on 

OS_MILLISECONDS timeLimit // max time to wait for the count to go to 
); 

Comments OSSemaWait is used with OSSemaSet and OSSemaReset to support event handling. In this model, the 

client waiting on the event should use OSSemaSet to set the semaphore to 1, and OSSemaWait to wait 
until the semaphore has been reset to 0. OSSemaReset will reset the semaphore to 0, thereby notifying 
the task waiting on the event. 

Retyrn Value stsOSSemaLockBroken Previous locker of semaphore died without clearing the semaphore 

stsOSTimeOut The timelimit expired before obtaining the semaphore 

See Also OSSemaReset 

OSFastSemalnit 

Initialize fast sema. 

Returns nothing.. 

#define OSFastSemalnit (_pSem) memset ( (_pSem) , 0, sizeof (OS_FAST_SEMA) ) 

Conirneiits Fast semaphores provide a fast but unprotected semaphore model. Fast semaphores are simply memory 

provided by the client as storage area for the state of the semaphore. This storage area must initially be 
set to 0. 

See Also OSFastSemaRequest 

OSFastSemaRequest 

Fast version of sema request. 

Returns STATUS. 

FoRcfion Frofolype STATUS EXPORTED OSFastSemaRequest ( 
P_OS_FAST_SEMA pSema 
); 

Cernnients OSFastSemaRequest should be used in conjunction with OSFastSemaClear when using semaphores to 

protect critical sections of code. OSFastSemaRequest/OSFastSemaClear implement a counting 
semaphore model which allows nesting of OSFastSemaRequest calls. Only after the same number of 
OSFastSemaClear calls will the next waiting task enter the critical section. Up to 64K nestings are 
allowed. 

Fast semaphores are fast by sacrificing protection. The semaphore structure passed into this routine is 
modified in the same privilege level as the caller. Only if another task owns the semaphore will a 
privilege level transition occur. 
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There are a number of important limitations that a developer should understand about fast semaphores. 

1) If a task owns a fast semaphore and then dies before releasing it, the 
semaphore will not be released automatically by the system. 

2) The fast semaphores should not be copied from one location to another. 
The routines rely on the address of the semaphore structure being 
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the same. w 



See Also OSFastSemaClear 



OSFastSemaClear 

Fast version of sema clear. 

Returns STATUS. 

Fuocfioti Prototype STATUS EXPORTED OSFastSemaClear ( 
P_OS_FAST_SEMA pSema 
); 

Comments OSFastSemaClear should be used in conjunction with OSFastSemaRequest when using semaphores to 

protect critical sections of code. OSFastSemaRequest/OSFastSemaClear implement a counting 
semaphore model which allows nesting of OSFastSemaRequest calls. Only after the same number of 
OSFastSemaClear calls will the next waiting task enter the critical section. Up to 64K nestings are 
allowed. 

Fast semaphores are fast by sacrificing protection. The semaphore structure passed into this routine is 
modified in the same privilege level as the caller. Only if another task is waiting on the semaphore will a 
privilege level transition occur. 

There are a number of important limitations that a developer should understand about fast semaphores. 

1) If a task owns a fast semaphore and then dies before releasing it, the 
semaphore will not be released automatically by the system. 

2) The fast semaphores should not be copied from one location to another. 
The routines rely on the address of the semaphore structure being 

the same. 
See Also OSFastSemaRequest 



OSGetTime 

Returns local time. 

Returns STATUS. 

Function Prototype STATUS EXPORTEDO OSGetTime ( 

SIZEOF structLength, // size of the date/time struct 

P_OS_DATE_TIME pDateTime // Out: date, time and time zone information 
); 

Comments If an error is returned, the time returned will be Jan 1, 1900. 
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OSSetTime 

Sets the time or time zone. 
Returns STATUS. 

STATUS EXPORTEDO OSSetTime ( 

OS_SET_TIME_MODE setMode, // which attributes to set 
SIZEOF structLength, // size of the date/time struct 
P_OS_DATE_TIME pDateTime // date, time and time zone information 

); 



OSProgramlnfo 

Returns information on the program from the loader. 

Returns STATUS. 

tion PmtotfpB STATUS EXPORTEDO OSProgramlnfo ( 

OS_PROG_HANDLE progHandle, // program handle given out by the loader 

P_OS_PROG_INFO pinfo // Out: information buffer 

); 

OSProgramlnfo will return information on the program handle passed in.no valid handle exists for that 

number, then the routine will returnon the numerically smallest program handle just largerthe 

number passed in. The program handle found will be put in theinformation buffer. If no valid 

handle exists that islarger than progHandle, then Nil will be returned in thehandle field of the 

information structure with stsOK beingfrom the function. 

To iterate over all program handles in the system, simply start byOSProgramlnfo with a progHandle of 
0. This will return thesmallest program handle. On the next call, use thathandle + 1, and on and on 
until the returned program handleO. 

OSPowerUpTime 

Passes back the number of milliseconds since the last reset. 
Returns OS_MILLISECONDS. 

OS_MILLISECONDS EXPORTEDO OSPowerUpTime (void) ; 



ScreenOnlyStringPrint 

Prints a string onto the console. 

Returns nothing. 

FyRcfion Prototype void EXPORTEDO ScreenOnlyStringPrint ( 

P_STRING pString // string to print 

); 

Comments This routine will not log output through the debug log. It will only display characters on the screen. 



Debugger 

Enters the debugger. 
Returns nothing. 



#ifdef DEBUG 

tdefine Debugger () OSDebugger() 
#else 

tdefine Debugger () 
#endif 
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Comments This macro will call the symbolic debugger (DB). If the symbolic debugger is not available the low-level 

kernel debugger is called. In production code (i.e., compiled without /DDEBUG) this macro does 
nothing. 



OSDebu^er 

Enters the debugger, should only be called in special situations. S 

Returns nothing. 



Fyncfion Prototype void EXPORTED OSDebugger (void) ; 

Commeots Most clients should call Debugger NOT OSDebugger. OSDebugger is used in special situations were a 

debugger needs to be called in production code. When a call to the production version of OSDebugger 
is made, the debug flag /DD 10000 must be set to actually enter the debugger. If the debug flag is not set 
the call is a NCP. 

NOTE: OSDebugger should only be called in exceptional cases, such as, page fault handling. 



KeyPressed 

Determines if a key is available. 
Returns BOOLEAN. 

fumt'mn Prototype BOOLEAN EXPORTED KeyPressed { 

P_U16 pCh // Out: the char if true is returned 

); 

Comments This routine is provided for support of low level code below the input system. 

The high byte of the key is the scan code. 
Setorn Value TRUE if a key is available 

FALSE if no key is available 
See Also Keyin 

Keyin 

Passes back the next key and the scan code from the keyboard. 

Returns a keyboard character. 
Fyncfioti Prototype U16 EXPORTEDO Keyin (void); 
Comments The Keyin routine is provided for support of low level code below the input system. 

The high byte of the key is the scan code. 
See Aiso KeyPressed 



OSDisplay 

Changes the display to the console or the graphics screen. 

Returns the old display mode. 

Foncfloo Prototype OS_DISPLAY_MODE EXPORTEDO OSDisplay ( 

OS_DISPLAY_MODE newDisplayMode // set the display mode. 

); 

Comments This call is only valid on single headed development systems. In all other configurations, the call does 

nothing. 
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OSSetlnterrupt 

Sets up an interrupt handler. 

Returns STATUS. 

fumtmn Prototype STATUS EXPORTED OSSetlnterrupt ( 

P_OS_INTERRUPT_INFO pintlnfo // In-Out: interrupt info 
); 

Comments The old interrupt info is also returned. Callable only in ring 0. 



OSTimerAsyncSema 

Reset a semaphore after time milliseconds. 

Returns STATUS. 

FyRciion Prototype STATUS EXPORTEDO OSTimerAsyncSema { 

OS_MILLISECONDS time, // waiting period before sema reset 
OS_SEMA_ID sema, // semaphore to reset 

P_OS_HANDLE pTransactionHandle // Out: ptr to transaction handle 
); 

Coninients The transaction handle can be used to stop the request if desired. 

OSTimerlntervalSema 

Resets a semaphore after each time interval has elapsed. 

Returns STATUS. 

FoRcfioii Prototype STATUS EXPORTEDO OSTimerlntervalSema { 

OS_MILLISECONDS timelnterval, // time interval in milliseconds 

OS_SEMA_ID sema, // semaphore to reset 

P_OS_HANDLE pTransactionHandle // Out: timer transaction handle 

); 

Comnients The transaction handle can be used to stop the request if desired. 

OSTimerStop 

Stops a timer request given its transaction handle. 

Returns STATUS. 

Prototype STATUS EXPORTEDO OSTimerStop ( 

OS_HANDLE transact ionHandle // transaction to stop 
); 



OSTimerTransactionValid 

Checks to see if the timer transaction is valid. 

Returns STATUS. 

efioo Prototype STATUS EXPORTEDO OSTimerTransactionValid ( 
OS_HANDLE transactionHandle 
); 
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OSModuleLoad 

Loads a module into the loader's database. 
Returns STATUS. 



STATUS EXPORTEDO OSModuleLoad { 
P_CHAR moduleName, 
P_CHAR pWorkingDir, 
P_OS_PROG_HANDLE pProgHandle, 
P CHAR pBadMod, 



P CHAR pBadReference 



// Module name or die name 

// Working dir of the app 

// Out: Program handle 

// Out: If error, name of module that 

// failed, buffer must be 

// maxModNameLength+1 long 

// Out: If error, ref name not understood 

// buffer must be maxModNameLength+1 long 



) 



If a die file is provided, all dlls in the file will also be loaded if not loaded already. 

OSModuleLoad will not return until instance of all loaded dlls are completed. No message 
dispatching will occur during this time. If communication to the calling task is required, use 
IMModuleLoad (install.h, install.lib). 

OSProgramlnstall 



OSEntrypointFind 



Finds an entrypoint in a loaded module either by name or by ordinal. 
Returns STATUS. 



Foncficr? Prototype STATUS EXPORTEDO OSEntrypointFind ( 
OS_ENTRYPOINT_TYPE entryType, 
P_STRING pName, 
U16 ordinal, 

OS_PROG_HANDLE progHandle, 
PP_MEM ppEntrypoint 

); 
See Also OSModuleLoad 



// name or ordinal 

// name if entryType is name 

// ordinal if entryType is ordinal 

// Program handle 

// Out: ptr to entrypoint address 



OSProcessProgHandle 

Passes back the program handle for the process. 
Returns the program instance number. 



» U16 EXPORTEDO OSProcessProgHandle ( 
P_OS_PROG_HANDLE pProgHandle 
); 



// Out: ptr to program handle 



OSEnvSearch 

Searches the environment for the specified variable and returns its value. 
Returns STATUS. 



function Prototype STATUS EXPORTEDO OSEnvSearch ( 
P_STRING pVariable, 
P_STRING outBuf, 
SIZEOF bufLen 
); 



// variable name 

// Out: Output buffer for variable value 

// output buffer length 
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OSTaskNameSet 

Sets a 4 character name for the given task. 

Returns STATUS. 

Fyncfiors Prototype STATUS EXPORTEDO OSTaskNameSet ( 

OS_TASK_ID taskid, // task to name 

P_CHAR name // name of task 

); 



OSThisApp 

Passes back the appHcation object stored with the current process. 
Returns OBJECT. 

|>c««.«yaK<^t«..vpr OBJECT EXPORTEDO OSThisApp (void) ; 



OSTaskApp 

Passes back the application object for a given process. 
Returns OBJECT. 

.l|.^„ »^^*^»^-^,» OBJECT EXPORTEDO OSTaskApp {OS_TASK_ID task) ; 

OSAppObjectPoke 

Stores the appHcation object for the current process. 

Returns nothing. 

Prototype void EXPORTEDO OSAppObjectPoke ( 

OBJECT object // current processes application object 

); 

OSPowerDown 

Powers down the machine. 
Returns nothing. 

Fofictlon Prototype void EXPORTEDO OSPowerDown (void) ; 

OSErrorBeep 

Outputs a tone based on the type of error encountered. 
Returns nothing. 

Function Prototype void EXPORTEDO OSErrorBeep ( 

OS_ERROR_TYPE errorType // type of error 

); 



OSTone 

Sends a tone for a given duration at the specified volume level. 
Returns STATUS, 

STATUS EXPORTEDO OSTone ( 

U16 frequency, // in Hertz 

U16 duration, // in milliseconds 

U16 volumeLevel // for off; 1 for on 

); 
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OSThisWinDev 

Passes back the windowing device for this appUcation. 



Returns OBJECT. J2 

Fwtict-ion Prototype OBJECT EXPORTEDO OSThisWinDev (void) ; ^ 



OSWinDevPoke 

Stores the windowing device for the specified process. 

Returns nothing. 

Fynctiorj Prototype void EXPORTEDO OSWinDevPoke { 

OS_TASK_ID process, // owner of application 
OBJECT winDev // Window device object 
); 

OSTaskProcess 

Returns the process id for the task specified. 

Returns OS_TASK_ID. 

function Prototype OS_TASK_ID EXPORTEDO OSTaskProcess ( 
OS_TASK_ID task 

); 



vf-m'^'icr^.N 



If the task parameter is invalid, the routine will return osNullTaskld. 



OSTasklnstallTerminate 

Notifies tasks waiting on OSProgramlnstall that the instance is finished. 

Returns nothing.. 

¥umt'mn Prototype void EXPORTEDO OSTasklnstallTerminate ( 
BOOLEAN wait 

); 

Comments If the parameter is set the TRUE, then the caller will go into an infinite wait state in order to keep the 

task and it's allocated resources alive. 



OSMemlnfo 

Returns information on memory usage for a specified task. 

Returns STATUS. 

mctmn Prototype STATUS EXPORTEDO OSMemlnfo ( 

SIZEOF memBufSize, // size of the info buffer (in bytes) 

P_OS_MEM_INFO pMemlnfo // Out: info buffer 

); 



OSMemUselnfo 

Returns information on memory usage for a specified task. 

Returns STATUS. 

mcfion Protofyfie STATUS EXPORTEDO OSMemUselnfo ( 

SIZEOF memBufSize, // size of the info buffer (in bytes) 

P_OS_MEM_USE_INFO pMemlnfo // Out: info buffer 

); 
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OSMemAvailable 

Return amount of swappable memory available (to caution zone). 

Returns STATUS. 

Fyncfion Prototype STATUS EXPORTED OSMemAvailable ( 
P_U32 pAvailable 

); 

OSSystemlnfo 

Passes back information on the system configuration. 

Returns STATUS. 

Fwnctiort Prototype STATUS EXPORTED OSSystemlnfo ( 

SIZEOF bufSize, // size of the info buffer (in bytes) 

P_OS_SYSTEM_INFO pSystemlnfo // Out: info buffer 

); 

osPrintBufferRoutine 

Function variable print routine. 
Returns nothing.. 

roncf ion Prototype extern void FunctionPtr (osPrintBufferRoutine) {P_CHAR pStr, SIZEOF len) ; 
Qomments All debug out (Debugf, DPrintf, printf, etc) flows through this function. 




OSHEAP.H 



This file describes the heap memory management routines. 
Heaps are used to allocate local and shared memory efficiently. 
The functions described in this file are contained in PENPOINT.LIB. 



Introduction 

Heaps allocate regions of virtual memory and manage the allocation and freeing of smaller blocks within 
those regions. 

Heaps have many different characteristics which are specified when the heap is created (see 
OSHeapCreate). For example, heaps can be shared (i.e. put in the shared memory space) or local. 

A heap is identified by a heap handle. PenPoint pre-defines two heap handles for each process, as 
described below. OSHeapCreate also returns the handle of a new heap. Most heap routines take the 
heap handle as a parameter to identify the heap. 

Pre-defined Heaps 

PenPoint pre-defines two heaps for every process. These heaps can be used without calling 
OSHeapCreate. 

osProcessHeapId is the handle for the pre-defined local heap in each process. 

osProcessSharedHeapId is the handle for the shared heap. The shared heap behavior is the same as the 
local heap except that the shared heap resides in shared memory. Blocks allocated from the shared heap 
are accessible from any process. 

Quick Start 

Many clients call only the following functions, using one of the two pre-defined heaps. 

♦ OSHeapBlockAlloc 

♦ OSHeapBlockFree 

Clients who need to create their own heaps also call the following functions: 

♦ OSHeapCreate 

♦ OSHeapDelete 

Debugging Flags 

Heap Manager debugging flag set is '*'. Defined flags are: 

1 : Validate heap before OSHeapBlockAlloc and before OSHeapBlockFree 
2: Display message for each heap block allocate and free 

4: Display message for each heap create and delete 10: Validate heap after OSHeapBlockAlloc and 
after OSHeapBlockFree 20: Display messages about internal region operation (private) 
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1000 Display messages about the internal workings (private) 
8000 Enter the debugger after printing warnings. 

Memory Overhead 

A heap consists of the memory allocated by the client plus the structures needed by the heap manager 
itself to maintain the heap. This section describes the overhead imposed by these structures. 

A heap is constructed as a collection of REGIONS. The overhead for a region is 36 bytes. By default, 
regions are 16Kb long; however, a request larger than -16K causes the creation of a special region whose 
size is a multiple of 4K and large enough to handle the request. 

Each region have any number of allocated blocks within it. The overhead of an allocated block (beyond 
the size requested) is 4 bytes, plus 0-3 bytes as necessary to pad the whole block up the nearest 32-bit 
boundary. 

tifndef OSHEAP_INCLUDED 
#define OSHEAP_INCLUDED 

#ifndef GO_INCLUDED 

tinclude <go.h> 
#endif 
#ifndef OSTYPES_INCLUDED 

#include <ostypes.h> 
#endif 

Common #clefiiies and typedefs 

Heap attributes for OS HeapCreate 

Enuml6(0S_HEAP_M0DE) { 

osHeapLocal =0, // heap is local to the owning process 

osHeapShared = flagO, // heap is accessible by all processes 

osHeapReadWrite =0, // heap is writable 

osHeapReadOnly = flagl, // heap is only readable 

osHeapOptSpace =0, // heap is optimized for space 

osHeapOptTime = flag2, // heap is optimized for speed 

osHeapWaitForMem =0, // wait for memory to become available 

osHeapOutOfMemErrOK = flagS // doesn't wait, returns out-of-memory error 
// flags 5-10 reserved as supervisor flags 

}; 

Heap information 

typedef struct OS_HEAP_BLOCK_INFO { 

SIZEOF numBlocks; // total number of blocks 

SIZEOF totalSize; // total # bytes in all blocks 

SIZEOF minSize; // # bytes in smallest block 

SIZEOF maxSize; // # bytes in largest block 
} OS_HEAP_BLOCK_INFO, * P_OS_HEAP_BLOCK_INFO ; 

typedef struct OS_HEAP_INFO { // info on a given heap 

OS_HEAP_BLOCK_INFO alloc; // info for allocated blocks 

OS_HEAP_BLOCK_INFO free; // info for free blocks 

U32 numRegions; // # regions in heap 

U32 committedSize; // # bytes committed 

U32 decommittedSize;// # bytes decommitted 

U32 reservedSize; // # bytes reserved 

U32 numOwners; // # tasks which have heap open 

OS_HEAP_MODE heapMode; // Mode used in heap creation 

} OS_HEAP_INFO, * P_OS_HEAP_INFO; 

tdefine OSTaskSharedHeapId(t) ((OS HEAP_ID)OSTaskProcess(t) ) 
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OSHeapCreate 

111 

Creates a heap. ^ 

Returns STATUS. 3> 

STATUS EXPORTED OSHeapCreate ( £ 

OS_HEAP_MODE mode, // heap create mode ^ 

SIZEOF size, // initial region size 

P_OS_HEAP_ID pHeapId // Out: heap id 

); 

Comments The size of the initial region allocated by the heap manager is a parameter to OSHeapCreate. If the 

amount of memory required by the heap is more than the size of the initial region, the heap manager 
allocates additional regions of 16K or the last request size, whichever is larger. An initial region size of 
will default to 16K. 

RettjrR Value stsOSRequestTooBig The requested size is greater than maxS32. 

stsOutOfMem The heap cannot be created because there is not enough memory available within the 
system. 

stsBadParam The mode parameter specified an illegal mode. 

See .4is« OSHeapDelete 

Deletes a heap. Frees all memory allocated by clients and by the heap manager. 
Returns STATUS. 

'unction Prof&typ& STATUS EXPORTED OSHeapDelete ( 

OS_HEAP_ID heapid // heap id of heap to delete 

); 

Comments Even heap blocks that are still allocated are deleted. 

If other tasks have opened the heap (using OSHeapOpen), the heap is not actually deleted until all tasks 
that have opened the heap have closed it (using OSHeapClosed). Note that this routine is similar to 
calling OSHeapClose with the current task. 

leium ¥siye stsOSInvalidHeapId The heapid was invalid or inaccessible. 

fee Also OSHeapCreate 



OSHeapAllowError 

Changes the "out of memory" behavior of heap block allocation. 
Returns OS_HEAP_ID. 

tdefine OSHeapAllowError (heap) \ 

{ (OS_HEAP_ID) ( (U32) (heap) losHeapIdOutOfMemErrOKBit) ) 
#define osHeapIdOutOfMemErrOKBit flagO 

Normally when a heap block is requested, the heap manager returns only when the memory is available. 
Calling OSHeapAllowError changes the heap so that if the system has insufficient memory the heap 
manager returns immediately with stsOutOfMem. 
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OSHeapClear 

Clears a heap. Deletes all the allocated heap blocks but not the heap. 

Returns STATUS, 

mctiosi Prototype STATUS EXPORTED OSHeapClear ( 

OS_HEAP_ID heapid // heap id of heap to clear 

); 

stum Value stsOSHeapOpen Heap has multiple owners and cannot be cleared. 

stsOSInvalidHeapId The heapid was ilnvalid or inaccessible. 
» Also OSHeapDelete 



OSHeapBlockAlloc 

Allocates a block within the heap. 

Returns STATUS. 

hmtfmn Prototype STATUS EXPORTED OSHeapBlockAlloc ( 

OS_HEAP_ID heapid, // heap id 

SIZEOF size, // size of block to allocate 

PP_UNKNOWN ppHeapBlock // Out: pointer to new heap block 

); 

:omnients The memory for the heap block is obtained from the list of regions in the heap. If a heap allocate 

request is larger than the available space in the region, a new region is allocated for the request. 

The newly allocated block is at least as large as the requested length. Sometimes, the heap manager 
allocates a block larger than the requested size. Heap blocks are always allocated on 32-bit boundaries. 

Heap blocks are allocated on behalf of the creator of the heap. Even if the allocate occurs in a different 
task than the creator, the new memory is owned by the creator of the heap. 

WARNING. This function expects a valid heap identifier. Using an invalid heap identifer can cause 
unpredictable results (including a page fault). A heapid for a heap that has been deleted is considered to 
be invalid. 

fee Also OSHeapBlockFree 

tefiirn Voiue stsOSRequestTooBig The requested block size greater than maxS32. 

stsOutOfMem The heap cannot grow any bigger because the system is out of memory. 

StsOSInvalidHeapId The heapid given is invalid. 

stsOSHeapIntegrityError The heap has been corrupted (heap flag 1). 



OSHeapBlockFree 

Frees a heap block. 

Returns STATUS. 

STATUS EXPORTED OSHeapBlockFree ( 

P_UNKNOWN pHeapBlock // pointer to heap block 

); 

WARNING. This function expects a valid heap block. Using an invalid heap block can cause 
unpredictable results (including a page fault). 
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See Also OSHeapBlockAlloc 

Refyrn ¥0lue stsOSInvalidHeapId The heapid given is invalid. 

stsOSHeapIntegrityError The heap has been corrupted (heap flag 1) or heap block pointer is bad 

(debug only). S 

stsBadParam The heap block pointer is bad (debug only). 8} 



OSHeapBlockResize 

Resizes a heap block. 

Returns STATUS. 

fumt'mn Prototype STATUS EXPORTED OSHeapBlockResize ( 

SIZEOF newSize, // new size to allocate 

PP_UNKNOWN ppHeapBlock // Out: New pointer is returned here. 

); 

Comments The heap block is resized to the new size. This may be slightly faster than allocating a new block and 

copying the original block's contents. 

After the call the heap block may be identified with a new pointer value, which is returned in 
*ppHeapBlock. 

The actual size of the new heap block may be slightly larger than the request. 

WARNING. This ftmction expects a valid heap block. Using an invalid heap block can cause 
unpredictable results (including a page fault). 

Passes back the heap id from which a heap block has been allocated. 

Returns OS_HEAP_ID. 

Function Prototype OS_HEAP_ID EXPORTED OSHeapId( 

P_UNKNOWN pHeapBlock // pointer to a heap block 

); 

Comments WARNING. This ftinction expects a valid heap block. Using an invalid heap block can cause 

unpredictable results (including a page fault). 



OSHeapBlockSize 

Passes back the size of the heap block. 

Returns STATUS. 

SyncfioR Prototype STATUS EXPORTED OSHeapBlockSize { 

P_UNKNOWN pHeapBlock, // pointer to the heap block 

P_SIZEOF pSize // Out: size of the heap block 

); 

:ommefits The size returned is the actual size of the heap block. This may be slightly larger than the requested size. 

WARNING. This ftinction expects a valid heap block. Using an invalid heap block can cause 
unpredictable results (including a page fault). 

lee Also OSHeapBlockAlloc 
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OSHeapPoke 

Stores 32 bits of client info in the heap header. 

Returns STATUS. 

Function Prototype STATUS EXPORTED OSHeapPoke ( 

OS_HEAP_ID heapid, // heap id 

P_UNKNOWN info // uninterpreted pointer stored in heap header 

); 

Comifseofs The client info is not interpreted by the heap manager. 

There is only client info field per heap; if more than one call is made to OSHeapPoke, the most recent 
caller determines the value stored. 

WARNING. This function expects a valid heap identifier. Using an invalid heap identifer can cause 
unpredictable results (including a page fault). An heapid for a heap that has been deleted is considered 
to be invalid. 



OSHeapPeek 

Passes back the client info previously set via OSHeapPokeQ. 

Returns STATUS. 

¥umfmn Prototype STATUS EXPORTED OSHeapPeek ( 

OS_HEAP_ID heapid, // heap id 

PP_UNKNOWN pinfo // Out: pointer stored by OSHeapPoke 

) ; 

Comments WARNING. This fiinction expects a valid heap identifier. Using an invalid heap identifer can cause 

unpredictable results (including a page fault). A heapid for a heap that has been deleted is considered to 
be invalid. 

OSHeapInfo 

Passes back information on a heap. 

Returns STATUS. 

fumfmn Prototype STATUS EXPORTED OSHeapInfo ( 

OS_HEAP_ID heapid, // heap id 

SIZEOF heapInfoSize, // size of heap info buffer 

P_OS_HEAP_INFO pHeapInfo // Out: heap info buffer 

); 

Ueturn Vobe stsOSInvalidHeapId The heapid was invalid or inaccessible. 

stsOSHeapIntegrityError The heap has been corrupted. Under debug version additional info is 
printed. 



OSHeapOpen 

Adds the specified task as an owner of the specified heap. 

Returns STATUS. 

Function Profofype STATUS EXPORTED OSHeapOpen ( 

OS_HEAP_ID heapid, // heap id 

OS_TASK_ID taskid // task to add as an owner 

); 
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Heaps are owned by the task that creates them. When the task is destroyed the heap is automatically 
destroyed. If one task wants to access another task's heap, the heap should be opened. Opening a heap is 
not required, but if the task owning the heap is destroyed while the second task is accessing the heap, the 
second task will fault. 



Memory resources allocated in the heap are not actually destroyed until the last owner of the heap ^ 

deletes the heap. Note that if the heap is opened multiple times by the same owner, a corresponding 
OSHeapClose or OSHeapDelete must occur for each before resources are deallocated. 

The kernel automatically destroys heap resources when all of the owners of the heap have terminated. 

The heap is automatically opened on the behalf of the creator during an OSHeapCreate. 

iefiirn ¥Qlije stsOSInvalidHcapId The heap must be a shared heap to be opened, the heapid was invalid or 

inaccessible. 

See Also OSHeapCreate 

OSHeapClose 

Remove the specifed task as an owner of the specified heap. 

Returns STATUS. 

Fyticfioii Prototype STATUS EXPORTED OSHeapClose ( 

OS_HEAP_ID heapid, // heap id 

OS_TASK_ID taskid // task to remove as an owner 

); 

Corariierifs When the heap has been closed by the last owner, the heap is automatically deleted. 

ieturn Vslue stsOSInvalidHeapId The heapid was invalid or inaccessible. 

See Also OSHeapClose 

OSHeapEnumerate 

Enumerates all the heaps in the given process. 

Returns STATUS. 

FyrKtion Pr©f€%*pe typedef STATUS FunctionPtr(P_OS_HEAP_ENUMERATE) ( 

OS_HEAP_ID heapid, // next heap 

OS_HEAP_MODE heapMode, // mode of heap 

P_UNKNOWN clientData // client data of OSHeapEnumerate 

); 

Fyncficiii Frototype STATUS EXPORTED OSHeapEnumerate ( 

P_OS_HEAP_ENUMERATE pEnumP roc , 

P_UNKNOWN ClientData // passed EnumProc on each call 

); 

Comments For each heap in the current process, OSHeapEnumerate calls the supplied callback procedure. This 

routine is supplied with a heapid and its mode. 

OSHeapEnumerate continues until it has exhausted all the heaps in the current process or the callback 
routine returns an error status. If the callback procedure returns an error status, processing is terminated 
and the error status is returned to the caller of OSHeapEnumerate. 

Retwrii Value stsOSInvalidHcapId The heapid was invalid or inaccessible. 

See Also OSHeapWalk 



P UNKNOWN 


pBlock; 


// 


U32 


size; 


// 


BOOLEAN 


inUse; 


// 


P UNKNOWN 


clientData; 


// 
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Traverses the given heap. 

Returns STATUS. 

typedef struct OS_HEAP_WALK_INFO { 

// address of heap block 
size of block 

true if the block is allocated 
set to the client data of OSHeapWalk 
// The following fields are only supported by a debugging version of 
// PenPoint's kernel. Changing their value modifies the heap block. 
BOOLEAN marked; // true if the block was marked w/OSHeapMark 

OS_TASK_ID owner; //last task to allocate or free this block 

P_UNKNOWN caller; // address of the last OSHeapBlockAlloc/Free 

} OS_HEAP_WALK_INFO, * P_OS_HEAP_WALK_INFO ; 
typedef STATUS FunctionPtr (P_OS_HEAP_WALK) (P_OS_HEAP_WALK_INFO pinfo) ; 

tion Fmfotype STATUS EXPORTED OSHeapWalk ( 

OS_HEAP_ID heapid, // heap to walk 

P_OS_HEAP_WALK pWalkProc, // procedure to call for each heap block 

P_UNKNOWN clientData // passed directly to pWalkProc 

); 

meiits For each allocated block in the given heap, calls the supplied callback routine, providing the address and 

size of the block. OSHeapWalk continues until it has exhausted all allocated blocks in the heap or the 
callback routine returns an error status. If the callback procedure returns an error status, processing is 
terminated and the error status is immediately returned to the caller of OSHeapWalk. 

m ¥ciiue stsOSInvalidHcapId The heapid was invalid or inaccessible. 

Also OSHeapEnumerate 

OSHeapMark 

Marks all the allocated blocks in given heap. 

Returns STATUS. 

tion Prototype STATUS EXPORTED OSHeapMark ( 

OS_HEAP_ID heapid // heap to mark 

); 

rfierris Combining OSHeapMark with OSHeapWalk provides a simple means to track down storage leaks. For 

example: 

// Program is in a known state 
OSHeapMark (myHeap) ; 

// Lots of OSHeapBlockAlloc/Free calls 
OSHeapBlockAlloc (myHeap, xx, &blk) ; 
OSHeapBlockFree (blk) ; 

// Program is back to the known state. 

// Any unmarked heap blocks probably indictate a storage leak 

OSHeapWalk (myHeap, MyHeapWalker) ; 



tetyrn 



StsOSInvalidHcapId The heapid was invalid or inaccessible. 
OSHeapWalk 
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// Don't print the free blocks 

// Don't print the allocated blocks 

// Don't print the marked blocks 

// Don't print the unmarked blocks 

// Don't print the heap summary 

// Print regions in heap 

// Display summary and all blocks 

// Display summary 



OSHeapPrint 

Prints debugging info about the given heap. 
Returns STATUS. 

Argymenis typedef enum OS_HEAP_PRINT_FLAGS { 

osHeapSuppressFree = flagO, 

osHeapSuppressInUse = flagl, 

osHeapSuppressMarked = flag2, 

osHeapSuppressUnmarked = flagS, 

osHeapSuppressSummary = flag4, 

osHeapDisplayRegions = flagS, 

osHeapPrintAll = 0, 

osHeapPrintSummaryOnly = 

osHeapSuppressFree | osHeapSuppressInUse | 
OsHeapSuppressMarked | osHeapSuppressUnmarked, 

// Show blocks created since the last call to OSHeapMark 

osHeapPrintActiveBlocks = osHeapSuppressFree | osHeapSuppressMarked 
} OS_HEAP_PRINT_FLAGS/ 
STATUS EXPORTED OSHeapPrint (OS_HEAP_ID heapid, OS_HEAP_PRINT_FLAGS suppress); 

Comments OSHeapPrint is only available in a debugging version of the PenPoint kernel. This request is not 

supported in production versions of Penpoint. 

OSHeapPrint assumes the heap is not corrupted; in other words, OSHeapPrint does not duplicate any 
of the integrity tests done by OSHeapInfo. 

Retyrn Value stsOSInvalidHeapId The heapid was invalid or inaccessible. 

Flags for OSHeapPrint 
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OSPRIV.H 



This include file describes tlie prototypes for supervisor privilege PenPoint routines. The functions 
described in this file are contained in PENPOINT.LIB. 

tifndef OSPRIV_INCLUDED 
tdefine OSPRIV_INCLUDED 
#ifndef OS_INCLUDED 
tinclude <os.h> 
#endif 

Common #defines and iypedefs 

The following are heap modes for supervisor level clients 

#define osHeapSupervisor flag5 // heap memory access is limited to supervisor 

tdefine osHeapNoSwap flag6 // heap memory is never swapped 

tdefine osHeapSystem flaglO // heap is owned by the system not a process 



Special heap defines for supervisor level clients 
#define osGlobalHeapId ( (OS_HEAP_ID) 10) 
Physical address types 



typedef U32 

typedef OS_PHYS_ADDR * 

Program region information 



OS_PHYS_ADDR; 
P OS PHYS ADDR; 



// predefined heap for sys clients 
// physical mem address 



typedef struct OS_PROGRAM_REGION_INFO { 

P_MEM base; 

SIZEOF length; 
} OS PROGRAM REGION INFO, *P OS PROGRAM REGION INFO; 



Functions 



OSIntMask 

Sets the interrupt mask for a given interrupt. 
Returns STATUS. 



Fynction Prototype STATUS EXPORTED OSIntMask { 
OS_INTERRUPT_ID intNum, 
P_BOOLEAN pEnable 
); 



// logical interrupt id 

// In-Out: TRUE = enable, returns old mask 



Note: OR in the flag osIntNumlsHardwareLevel if intNum is a hardware interrupt level (vs a MIL 
logical device id). The flag is defined in ostypes.h. 

Warning!!! Supervisor privilege only. 



166 PENPOINT API REFERENCE 

Part 8 / System Services 



OSIntEOI 

Send an EOI request to the interrupt controller device. 

Returns STATUS. 

STATUS EXPORTED OSIntEOI ( 

OS_INTERRUPT_ID intNum // MIL device id or hw interrupt level 

); 

Note: OR in the flag osIntNumlsHardwareLevel if intNum is a hardware interrupt level (vs a MIL 
logical device id). The flag is defined in ostypes.h. 

Warning!!! Supervisor privilege on^. 

OSProgramRegionlnfo 

Passes back region information for the debugger. 
Returns STATUS. 

STATUS EXPORTED OSProgramRegionlnfo ( 

OS_PROG_HANDLE progHandle, // program handle 

P_U32 pNRegions, // Out: number of regions 

P_OS_PROGRAM_REGION_INFO pRI // Out: region information 

); 

Warning!!! Supervisor privilege on^. 

OSSysSemaRequest 

Requests access to a system semaphore. 

Returns STATUS. 

STATUS EXPORTED OSSysSemaRequest ( 

OS_SEMA_ID sema // the semaphore to lock 
); 

System semaphores are regular semaphores with a little more protection. If a task owns a system 
semaphore, then that task cannot be terminated or suspended by another task until the system 
semaphore is relinquished. With this feature, tasks can be sure that any system critical data structures 
will be completely updated. 

If the task terminates itself while it owns a system semaphore, then the next task that acquires the system 
semaphore will get the warning stsOSSemaLockBroken. 

OSSysSemaClear should be used to relinquish the system semaphore. The function OSSemaCreate is 
used to create the system semaphore. Any semaphore can become a system semaphore simply by calling 
this routine. System semaphores are only used for critical section management. Do NOT use system 
semaphores for event handling. 

Like regular semaphores, system semaphores are counting semaphores. 

Warning!!! Supervisor privilege only. 

StsOSSemaLockBroken Previous locker of semaphore died without clearing the semaphore 

OSSemaCreate 
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Functions 



OSSysSemaClear 

Releases access to the the system semaphore. 
Returns STATUS. 



u 



'umtmn Prototype STATUS EXPORTED OSSysSemaClear ( ^ 

OS_SEMA_ID sema // the semaphore to unlock 

); 



System semaphores are regular semaphores with a little more protection. If a task owns a system 
semaphore, then that task cannot be terminated or suspended by another task until the system 
semaphore is relinquished. With this feature, tasks can be sure that any system critical data structures 
will be completely updated. 

If the task terminates itself while it owns a system semaphore, then the next task that acquires the system 
semaphore will get the warning stsOSSemaLockBroken. 

OSSysSemaClear should be used to relinquish the system semaphore. The function OSSemaCreate is 
used to create the system semaphore. Any semaphore can become a system semaphore simply by calling 
OSSysSemaRequest/ OSSysSemaClear. System semaphores are only used for critical section 
management. Do NOT use system semaphores for event handling. 

Like regular semaphores, system semaphores are counting semaphores. 

Warning!!! Supervisor privilege only. 

OSSysSemaRequest 



OSSupervisorCall 

Performs a privilege transition to supervisor privilege. 
Returns U32. 

#if defined (__WATCOMC ) && defined ( 386 ) 

tpragma aux OSSupervisorCall parm [eax] [edx] [ecx] modify [gs]; 



Function Prototype U32 far OSSupervisorCall ( 

P_UNKNOWN pFunction, 
P_UNKNOWN pStackParms, 
U32 nStackParms 

); 

#endif 



The function passed into the routine will be called by OSSupervisorCall in supervisor privilege. This 
function will check to verify that the routine passed in is actually a supervisor level routine. 

OSSupervisorCall will work correctly if called in supervisor level. 



OSTaskAddressInfo 

Passes back task and system memory information. 
Returns STATUS. 

STATUS EXPORTED OSTaskAddressInfo { 

P_MEM pAddr, // memory address 

OS_TASK_ID owner, // owner of address 

SIZEOF statBufSize, // size of info buffer (in bytes) 

P_OS_ADDRESS_INFO pAddrlnfo // Out: info buffer 

); 

Warning!!! Supervisor privilege only. 
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Data structures used by OSResourcesAva liable 



Enuml 6 (OS_RESOURCE_ZONE ) { 

osResourceZoneNormal, // Normal: plenty of resource 

osResourceZoneCaution, // Caution: resource is getting low 

osResourceZoneWarning, // Warning: resource is low 

osResourceZoneDanger, // Danger: resource is really low 

osResourceZoneCritical // Critical: PenPoint will reboot 

}; 

#define numResourceZones 5 

typedef struct OS_RESOURCE_AVAILABLE { 

OS_RESOURCE_ZONE currenfZone; 

U32 resourceAvailable; 

U32 zoneLimits [numResourceZones] ; 

} OS_RESOURCE_AVAILABLE, *P_OS_RESOURCE_AVAILABLE; 

typedef struct OS_RESOURCES_INFO { 

OS_RESOURCE_AVAILABLE swappableMemory; 

OS_RESOURCE_AVAILABLE nonSwappableMemory ; 

OS_RESOURCE_AVAILABLE objects; 
} OS_RESOURCES_INFO, *P_OS_RESOURCES_INFO; 

OSResourcesAvailable 

Returns info on the available resources in the system. 

Returns STATUS. 

Ml P'-mmtfps STATUS EXPORTEDO OSResourcesAvailable ( 

SIZEOF bufSize, // size of the info buffer (in bytes) 

P_OS_RESOURCES_INFO pinfo // Out: info buffer 

); 

OSMemMapAlloc 

Allocates linear memory for memory mapped hardware 

Returns STATUS. 

m Pmmype STATUS EXPORTED OSMemMapAlloc ( 

U32 physAddr, // address of memory mapped area 

U32 length, // length of memory to allocate 

PP_MEM ppMem // Out: return ptr to the memory 

); 

ents Creates a guard page after the memory. The memory is created with the attributes: read/write data, 

system privilege, owned by systemTId. 

Note: the physical address passed in physAddr must be within the first 16MB of physical memory. 

Warning!!! Supervisor privilege on^. 

OSMemMapFree 

Frees memory which was allocated by OSMemMapAlloc 

Returns STATUS. 

m Pmmtfpe STATUS EXPORTED OSMemMapFree ( 

P_MEM pMem // ptr to memory to free 

); 

ents Warning!!! Supervisor privilege only. 
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Function Prototype 



OSDMAMemAlloc 

Allocates linear memory that is DMA-able 
Returns STATUS. 

STATUS EXPORTED OSDMAMemAlloc ( 
U32 length, 

OS_TASK_ID owner, 
PP_MEM ppMem 

); 



// length of memory to allocate 

// owning task id. 

// Out: return ptr to the memory 



Creates a guard page after the memory. The memory is created with the following attributes: 

read/write access 

supervisor privilege 

Not swappable (every page locked). 

All pages are mapped in and are physically contiguous in memory. For machines that have DMA 
boundary conditions (e.g. can't cross 64k physical boundary), the memory allocated in this region is 
guaranteed to honor those conditions. Memory will be allocated on system page size boundaries and all 
allocations will be a minimum of the processor page size. 

Warning!!! Supervisor privilege only. 



OSDMAMemFree 

Frees memory which was allocated by OSDMAMemAlloc 
Returns STATUS. 



STATUS EXPORTED OSDMAMemFree ( 
P_MEM pMem, 

OS_TASK_ID owner 

); 

Warning!!! Supervisor privilege only. 



// ptr to memory to free 
// owning task id. 



OSTaskMeniInfo 

Provides memory info for the system. 
Returns STATUS. 

STATUS EXPORTED OSTaskMemlnfo ( 
OS_TASK_ID taskid, 
SIZEOF memBufSize, 
P_OS_MEM_INFO pMemlnfo 

); 

Warning!!! Supervisor privilege onfy". 



// info will be returned for task id 
// size of the info buffer (in bytes) 
// Out: info buffer 



OSVirtToPhys 



Translates a virtual address into a physical address. 
Returns U32. 

Fynctioti Profotype U32 EXPORTED OSVirtToPhys { 



P_UNKNOWN pMem 



// virtual address 



); 



Warning!!! Supervisor privilege only. 
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OSMemLock 

Locks pages in memory. 

Returns STATUS. 

I\i«€licri Prototype STATUS EXPORTED OSMemLock ( 

P_MEM pMem, // pointer to memory 

SIZEOF length // length in bytes of memory to lock 

); 

Cemrrients Locked pages will not be paged out of the system. If the page is paged out before this call, then the page 

will be brought into memory and then locked. 

A counter is maintained to keep track of multiple locks on a given page. 

Warning!!! Supervisor privilege on]y. 

OSMemUnlock 

Unlocks pages in memory. 

Returns STATUS. 

Fyncficin Prototype STATUS EXPORTED OSMemUnlock ( 

P_MEM pMem, // pointer to memory 

SIZEOF length // length in bytes of memory to unlock 

); 

CotiiiTients When the page is unlocked, it may be paged out by the memory manager. 

A counter is maintained to keep track of multiple locks on a given page. When the counter goes to 
then the page will be unlocked. 

Warning!!! Supervisor privilege on]y. 
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OSTYPES.H 



Module Description: This include file describes types for the Penpoint kernel. 

tifndef OSTYPES_INCLUDED 
#define OSTYPES_INCLUDED 

tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 



Defines 



♦ Status values: errors 



#define 


stsOSBadPointer 


MakeStatus (clsOS 


1) 


tdefine 


stsOSOutOfMem 


stsOutOfMem 




tdefine 


stsOSNoMoreOwners 


MakeStatus 


clsOS 


3) 


tdefine 


stsOSInvalidPath 


MakeStatus 


clsOS 


4) 


tdefine 


stsOSNoSemaExists 


MakeStatus 


ClsOS 


5) 


tdefine 


stsOSTimeOut 


MakeStatus 


ClsOS 


6) 


tdefine 


stsOSSemaReset 


MakeStatus 


ClsOS 


7) 


tdefine 


stsOSAliasesExist 


MakeStatus 


clsOS 


8) 


tdefine 


stsOSInvalidOperationForTask 


MakeStatus 


clsOS 


9) 


tdefine 


stsOSInvalidTaskId 


MakeStatus 


clsOS 


10) 


tdefine 


stsOSTransactionlnvalid 


MakeStatus 


ClsOS 


11) 


tdefine 


stsOSRequestTooBig 


MakeStatus 


clsOS 


12) 


tdefine 


stsOSHeapIntegrityError 


MakeStatus 


ClsOS 


13) 


tdefine 


stsOSInvalidHeapId 


MakeStatus 


clsOS 


14) 


tdefine 


stsOSSegmentDiscarded 


MakeStatus 


ClsOS 


16) 


tdefine 


stsOSFlashEraseFailure 


MakeStatus 


clsOS 


17) 


tdefine 


stsOSFlashProgramFailure 


MakeStatus 


clsOS 


18) 


tdefine 


stsOSBadExeFormat 


MakeStatus 


clsOS 


19) 


tdefine 


stsOSInstalllnternalError 


MakeStatus 


clsOS 


20) 


tdefine 


stsOSMissingEntryName 


MakeStatus 


clsOS 


21) 


tdefine 


stsOSMissingEntryOrdinal 


MakeStatus 


ClsOS 


22) 


tdefine 


stsOSInitiatelnternalError 


MakeStatus 


clsOS 


23) 


tdefine 


stsOSInitiateStackOverflow 


MakeStatus 


clsOS 


24) 


tdefine 


stsOSProglnstallError 


MakeStatus 


clsOS 


25) 


tdefine 


stsOSTooManySelectors 


MakeStatus 


clsOS 


26) 


tdefine 


stsOSTooManylnstances 


MakeStatus 


clsOS 


27) 


tdefine 


stsOSDependenciesExist 


MakeStatus 


clsOS 


28) 


tdefine 


stsOSTooManyRequireds 


MakeStatus 


clsOS 


29) 


tdefine 


stsOSPathTooLong 


MakeStatus 


clsOS 


30) 


tdefine 


stsOSModuleNotFound 


MakeStatus 


clsOS 


31) 


tdefine 


stsOSBadDLCFormat 


MakeStatus 


clsOS 


32) 


tdefine 


stsOSMissingDependency 


MakeStatus 


ClsOS 


33) 


tdefine 


stsOSInvalidProgramHandle 


MakeStatus 


clsOS 


34) 


tdefine 


stsOSHeapOpen 


MakeStatus 


clsOS 


35) 


tdefine 


stsOSHeapNotOpen 


MakeStatus 


ClsOS 


36) 



♦ Status values: warnings 
tdefine stsOSSemaLockBroken 



MakeWarning(clsOS, 1) 
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♦ Misc defines 

#define osNullTaskId 
tdefine osNullOpenSema 
tdefine osInvalidHandle 
tdefine osInfiniteTime 
Idefine maxModNameLength 

♦ Well known heap ids 

Idefine osInvalidHeapId 
tdefine osProcessHeapId 
tdefine osProcessSharedHeapId 

♦ Filters 



((OS_TASK_ID)NULL) 

((OS_SEMA_ID)NULL) 

((OS_HANDLE)NULL) 

OxFFFFFFFF 

32 



((OS_HEAP_ID)0) 

( (OS_HEAP_ID) &OSProcessHeapValue) 

{(OS HEAP ID)OSThisProcess()) 



tdefine osAnylTMessage OxFFFFFFFF 
tdefine osStartupCommandLineFilter flagO 

tdefine osClsmgrSend flagO 

tdefine osClsmgrReply flagl 

tdefine osMILFilter flag2 

tdefine osAppSend flagS 

tdefine osAppReply flag4 

tdefine osTestManagerFilter flag5 

tdefine osClsmgrPost flag6 

tdefine osInstallWaitingFilter flagSO 

tdefine osTerminatedTaskFilter flagSl 

NOTE: flag25 - flag29 reserved for users 

tdefine userDefinedFilters (flag25|flag26|flag27 |flag28|flag29) 

tdefine objSendFilter ( (OS_ITMSG_FILTER) osClsmgrSend) 

tdefine objReplyFilter ( {OS_ITMSG_FILTER) osClsmgrReply) 

Used to treat the intNum field as a hardware interrupt level (vs a MIL logical device id) in the routines 
OSSetlnterrupt, OSIntMask and OSIntEOI. 

tdefine osIntNumlsHardwareLevel flaglS 



Typedefs 



typedef P_UNKNOWN 
typedef U32 
typedef U16 
typedef OS_HANDLE 
typedef P_UNKNOWN 
typedef OS_HANDLE 
typedef U32 
typedef U16 
typedef U32 
typedef U32 

typedef P_MEM* 
typedef OS_HANDLE* 
typedef OS_TASK_ID* 
typedef OS_SEMA_ID* 
typedef OS_PROG_HANDLE* 
typedef OS_ITMSG_ID* 
typedef OS_ITMSG_FILTER* 
typedef OS_TASK_ERROR* 
typedef P_UNKNOWN 

typedef enum OS_TASK_MODE { 

osThisTaskOnly, 

osTaskFamily, 

osAllTasks 
} OS TASK MODE, * P OS TASK MODE; 



P_MEM; 

OS_HANDLE; 

OS_TASK_ID; 

OS_SEMA_ID; 

OS_PROG_HANDLE; 

OS_ITMSG_ID; 

OS_ITMSG_FILTER; 

OS_INTERRUPT_ID; 

OS_MILLISECONDS; 

OS_TASK_ERROR; 

PP_MEM; 

P_OS_HANDLE; 

P_OS_TASK_ID; 

P_OS_SEMA_ID; 

P_OS_PROG_HANDLE ; 

P_OS_ITMSG_ID; 

P_OS_ITMSG_FILTER; 

P_OS_TASK_ERROR; 

OS HEAP ID, * P OS 



// Pointer to memory 
// Handle to an object 
// Task Id 

// Open semaphore Id 
// Loaded program handle 
// message identifier 
// Inter-task msg filter 
// logical interrupt ID 
// number of milliseconds 



HEAP ID; 



// "act" on this task only 

// "act" on all tasks in the task family 

// "act" on all tasks in the system 
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typedef enum OS_PRIORITY_CLASS { 

osDefaultClass, // use existing class 

osHighPriority, // the class is "high priority" 

osMedHighPriority, // the class is "med high priority" 

osMedLowPriority, // the class is "med low priority" wi 

osLowPriority // the class is "low priority" y 

} OS_PRIORITy_CLASS, * P_OS_PRIORITY_CLASS ; ^ 

typedef struct OS_ITMSG_INFO* P_OS_ITMSG_INFO; 



Public Functions 



OSThisProcess 

Passes back the task id of this tasks process. 
Returns OS_TASK_ID. 

OS_TASK_ID EXPORTEDO OSThisProcess (void) ; 

Note: This function is defined here (instead of in os.h) to satisfy the definition for 
osProcessSharedHeapId above. 
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SORT.H 



Interfaces to sorting routines. 

This file contains the API definition for the quicksort sorting algorithm. 

NOTE: qsort can be found in stdlib.h 



#ifndef SORT_INCLUDED 
#define SORT INCLUDED 



Version 1.0 



Public Functions 



quicksort 

Sorts a linked list of records using the "quicksort" algorithm. 

Returns pointer. 

extern void ** quicksort (void **head, int (*comp) (void **, void **)); 

Usage: 

struct record *head; 

int comp (struct record *p, struct record *q) ; 

head = quicksort (head, comp) ; 

The routine "quicksort" takes an argument "head", which is a pointer to the first record of a linked list. 
It also takes an argument "comp", which is the name of a user-supplied routine for comparing two list 
records. The routine "comp" must take as its arguments a pointer to each of two list records, and must 
return an integer, either (-1) if the first record is "smaller than" the second, (0) if the first record is 
"equal to" the second, or (+1) if the first record is "larger than" the second. 

Afi;er sorting, "quicksort" returns a pointer to the new first record of the linked list (i.e., the new "head" 
of the list). 

The structure of the linked list records is as follows. The first field of each list record must be the "next" 
pointer. The actual data in the list records may be of variable size. 



+ + 

I head | — 
+ + 



+ + + + + + + + 

->| next I >| next | >| next | >| next | >pNull 

+ + + + + + + + 

I data I I data | | data | | data | 

I .... I I .... I I .... I I .... I 

I .... I + + I .... I I .... I 

+ + I .... I + + 



+- 



-+ 



The "quicksort" algorithm is fast. However, it is recursive. When there are N records in the list, the 
maximum recursion depth will average around (In N) calls. Each recursion puts about 30 bytes on 
the stack. 



r 
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TIMER.H 



This file contains the API definition for clsTimer. 

Notes: 

"theTimer" is a well known object that provides timer and alarm support. 

clsTimer inherits firom clsObject. 

#ifndef TIMER_INCLUDED 
tdefine TIMER_INCLUDED 

Include file dependencies for this include file 

tifndef GO_INCLUDED 

tinclude <go.h> 

#endif 

tifndef CLSMGR_INCLUDED 

♦include <clsmgr.h> 

#endif 

tifndef OS_INCLUDED 

#include <os.h> 

ttendif 



Class Timer Messages 



rn Value 



msgTimerRegister 

Registers a request for notification. 

Takes P_TIMER_REGISTER_INFO, returns STATUS. 

tdefine msgTimerRegister MakeMsg (clsTimer, 1) 

typedef struct TIMER_REGISTER_INFO { 

OBJECT client; // client object to notify 

OS_MILLISECONDS time; // waiting period before msg is sent 

P_UNKNOWN clientData; // Uninterpreted client data 
OS_HANDLE transactionHandle; // Out: transaction handle 

} TIMER_REGISTER_INFO, * P_TIMER_REGISTER_INFO; 

Sent by the client to the timer object for notification afi:er a specified time period has elapsed. At that 
time, msgTimerNotify will be sent (via ObjectPost) to the client. See that message for details. 

When the machine is turned off, the time period will stop counting down until the machine is turned 
back on. 

To stop the timeout message, use mtsgTimerStop. 

The use of ObjectPost to send the msgTimerNotify message means that it will be synchronous with 
input events. 

stsBadObject The client field cannot be a local object. 
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msgTimerRegisterAsync 

Registers a request for notification. 

Takes P_TIMER_REGISTERJNFO, returns STATUS. 

♦define msgTimerRegisterAsync MakeMsg(clsTimer, 9) 

typedef struct TIMER_REGISTER_INFO { 

OBJECT client; // client object to notify 

OS_MILLISECONDS time; // waiting period before msg is sent 

P_UNKNOWN clientData; // Uninterpreted client data 
OS_HANDLE transact ionHandl'e; // Out: transaction handle 

} TIMER_REGISTER_INFO, * P_TIMER_REGISTER_INFO; 

Sent by the client to the timer object for notification after a specified time period has elapsed. At that 
time, msgTimerNotify will be sent (via ObjectPostAsync) to the client. See that message for details. 

When the machine is turned off, the time period will stop counting down until the machine is turned 
back on. 

To stop the timeout message, use msgTimerStop. 

The use of ObjectPostAsync to send the msgTimerNotify message means that it will NOT be 
synchronous with input events. 

msgTimerRegisterDirect 

Registers a request for notification. 

Takes P_TIMER_REGISTER_INFO, returns STATUS. 

tdefine msgTimerRegisterDirect MakeMsg(clsTimer, 12) 

typedef struct TIMER_REGISTER_INFO { 

OBJECT client; // client object to notify 

OS_MILLISECONDS time; // waiting period before msg is sent 

P_UNKNOWN ClientData; // Uninterpreted client data 
OS_HMDLE transact ionHandle; // Out: transaction handle 

} TIMER_REGISTER_INFO, * P_TIMER_REGISTER_INFO; 

Sent by the client to the timer object for notification after a specified time period has elapsed. At that 
time, msgTimerNotify will be sent (via ObjectPostDirect) to the client. See that message for details. 

When the machine is turned off, the time period will stop counting down until the machine is turned 
back on. 

To stop the timeout message, use msgTimerStop. 

The use of ObjectPostDirect to send the msgTimerNotify message means that it will NOT be 
synchronous with input events. 

msgTimerRegisterlnterval 

Registers a request for interval notification. 

Takes P_TIMER_INTERVAL_INFO, returns STATUS. 

#define msgTimerRegisterlnterval MakeMsg(clsTimer, 2) 

typedef struct TIMER_INTERVAL_INFO { 

OBJECT client; // client object to notify 

OS_MILLISECONDS interval; // waiting interval before msg is sent 
P_UNKNOWN clientData; // Uninterpreted client data 
OS_HANDLE transact ionHandle; // Out: transaction handle 

} TIMER INTERVAL INFO, * P TIMER INTERVAL INFO; 
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Sent by the client to the timer for a notification message on a specified time interval. After each time 
interval, msgTimerNotify will be posted (via ObjectPost) to the client. 

When the machine is turned off, the time period will stop counting down until the machine is turned 

back on. iS 

u 

To stop the interval messages, use msgTimerStop. g 

The use of ObjectPost to send the msgTimerNotify message means that it will be synchronous with ^ 

input events. 

stsBadObject The client field cannot be a local object. 

msgTimerStop 

Stops a timer transaction. 

Takes OS_HANDLE, returns STATUS. 

#define msgTimerStop Mak;eMsg(clsTimer, 11) 

msgTimerTransactionValid 

Determines if a timer transaction is valid. 
Takes OS_HANDLE, returns STATUS. 

tdefine msgTimerTransactionValid MakeMsg(clsTimer, 10) 

msgTimerNotify 

Notifies the client that the timer request has elapsed. 

Takes P_TIMER_NOTIFY, returns nothing. Category: advisory message. 

#define msgTimerNotify MakeMsg(clsTimer, 3) 

Irgumenfs typedef Struct TIMER_NOTIFY { 

P_UNKNOWN clientData; // client data returned 

OS_HANDLE transact ionHandle; // transaction handle 

} TIMER_NOTIFY, * P_TIMER_NOTIFY; 

:c>miiieiits Sent by the timer object to the client. 



msgTimerAlarmRegister 

Registers a request for alarm notification. 

Takes P_TIMER_ALARM_INFO, returns STATUS. 

tdefine msgTimerAlarmRegister MakeMsg(clsTimer, 5) 

iraeiifs Enuml6(TIMER_ALARM_M0DE) { 

timerAbsoluteDate, // alarm only on specified date and time 

timerEveryWeek, // alarm when dayOfWeek, hours, minutes match 

timerEveryDay // alarm when hours and minutes match 

}; 

typedef struct TIMER_ALARM_INFO { 

OBJECT client; // client object to notify 

OS_DATE_TIME alarmTime; // alarm time 
P_UNKNOWN clientData; // Uninterpreted client data 
OS_HANDLE transact ionHandle; // Out: transaction handle 
TIMER_ALARM_MODE alarmMode; 

} TIMER ALARM INFO, * P TIMER ALARM INFO; 
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Alarms differ from timer requests in tiiat a time and date specifies when an alarm is to occur. The timer 
will ObjectPost msgTimerAlarmNotify to the client when the alarm goes off. See that message for 
details. 

Alarms will alarm within a minute of the alarm time. 

When the machine is turned off, the alarm is still active. An alarm will turn the machine on. 

To stop the alarm, use the message msgTimerAlarmStop. 

stsBadObject The client field cannot be a local object. 



msgTimerAlarmStop 

Stops a pending alarm request. 

Takes OS_HANDLE, returns STATUS. 

#define msgTimerAlarmStop MakeMsg{clsTimer, 6) 



msgTimerAlarraJMotify 

Notifies the client that the alarm request has elapsed. 

Takes P_ALARM_NOTIFY, returns nothing. Category: advisory message, 
tdefine msgTimerAlarmNotify MakeMsg(clsTimer, 7) 

typedef struct ALARM_NOTIFY { 

P_UNKNOWN clientData; // client data returned 

OS_HANDLE transact ionHandle; // transaction handle 

BOOLEAN alarmCausedPoweron; // power up occurred due to alarm 

} ALARM_NOTIFY, * P_ALARM_NOTIFY; 

Sent by the timer object to the client. 
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BKSHELF.H 



This file contains the API definition for clsDVBookshelf. 
clsDVBookshelf inherits fi-om clsIconWin. 

It provides a view of bookshelves on external disks. 

tifndef BKSHELF_INCLUDED 
♦define BKSHELF_INCLUDED 

tifndef APPWIN_INCLUDED 
#include <appwin.h> 
tendif // APPWIN_INCLUDED 

tifndef ICONWIN_INCLUDED 
tinclude <iconwin.h> 
tendif // ICONWIN_INCLUDED 

Common #defines and typedefs 

typedef struct BOOKSHELF_METRICS { 

U32 sparel; // Spare: reserved. 

U32 spare2; // Spare: reserved. 

} BOOKSHELF METRICS, *P BOOKSHELF METRICS; 



Arguments 



msgNew 

Creates a new bookshelf viewer. 

Takes P_BOOKSHELF_NEW, returns STATUS. Category: class message. 



typedef struct BOOKSHELF_NEW_ONLY { 

BOOKSHELF_METRICS metrics; 

OBJECT rootDH; 

OBJECT win; 

U32 reservedl; 

U32 reserved2; 

} BOOKSHELF_NEW_ONLY, *P_BOOKSHELF_NEW_ONLY; 

tdefine bookshelfNewFields \ 
iconWinNewFields \ 
BOOKSHELF_NEW_ONLY bookshelf; 

typedef struct BOOKSHELF_NEW { 

bookshelfNewFields 
} BOOKSHELF_NEW, *P_BOOKSHELF_NEW; 

msgBookshelRjetMetrics 

Gets current metrics setting. 

Takes P_BOOKSHELF_METRICS, returns STATUS. 

#define insgBookshelfGetMetrics 

typedef struct BOOKSHELF_METRICS { 

U32 sparel; // Spare: reserved. 

U32 spare2; // Spare: reserved. 

} BOOKSHELF METRICS, *P BOOKSHELF METRICS; 



// Initial metrics setting. 

// Dir handle of volume for this bkshelf . 

// Window for move/copy. 



MakeMsg (clsDVBookshelf, 1) 
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msgBookshelfSetMetrics 

Sets current metrics setting. 

Takes P_BOOKSHELF_METRICS, returns STATUS. 

tdefine msgBookshelfSetMetrics MakeMsg(clsDVBookshelf, 2) 



typedef struct BOOKSHELF_METRICS { 

U32 sparel; // Spare: reserved. 

U32 spare2; // Spare: reserved. 

} BOOKSHELF METRICS, *P BOOKSHELF METRICS; 



Miscellaneous 



// "— Empty — " label tag 

tdefine tagBookshelfEmpty MakeTag(clsDVBookshelf, 1) 

♦define hlpBKBook shelf Empty MakeTag(clsDVBookshelf, 100) 
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This file contains the API definition for clsBrowser. 

clsBrowser inherits from clsScrollWin. 

clsBrowser provides the UI for viewing and manipulating notebooks and disks. 

clsBrowser provides both the Table Of Contents view of "live" data in the notebook and the Disk 
Viewer view of "dead" data on disk. clsBrowser fiinctions include displaying notebook and disk items, 
navigating the notebook or file system hierarchy, move/copy of documents, export of notebook 
documents to disk, import of files from disks into the notebook, deleting notebook and disk items, and 
creating notebook and disk items. 

clsBrowser is usefiil to applications that need to allow users to select sections or documents in the 
notebook, or items from disk. 

Some messages apply only to the TOC view or to the disk view. Disk View only messages are labeled 
DskView only, TOC view only messages are labeled TOC only. 

Many browser messages are sent to self allowing subclasses to modify browser behavior. 

Move/Copy Conventions 

See embedwin.h for move/ copy protocol. 

When the source of a move/copy, the browser responds to msgXferGetList with: 

XferName can xfer the name of the selection 

XferFullPathName can xfer the full path name of the selection 

XferFlatLocator can xfer the flat locator of the selection 

clsFileSystem can xfer as a file or directory 

clsEmbeddedWin can xfer as "live" data notebook, section, or document 

clsExport If source is TOC and export mode is in effect then do export instead of copy, (see export.h 
for details) 

If the destination is the disk and the xferList contains clsExport then do export instead of move/copy. 

If not an export, and the xferList contains clsEmbeddedWin then let the embedded win superclass will 
handle the move/copy. 

If the destination is the TOC and source is not a clsEmbeddedWin then invoke the import code. 

Otherwise, if the source is clsFileSystem do a file system move or copy. 

#ifndef BROWSER_INCLUDED 
#define BROWSER_INCLUDED 

tifndef GO_INCLUDED 
♦include <go.h> 
tendif 
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tifndef UID_INCLUDED 
#include <uid.h> 
#endif 

#ifndef CLSMGR_INCLUDED 

tinclude <clsin.gr. h> 

#endif 

#ifndef FRAME_INCLUDED 

tinclude <fraine.h> 

#endif 

tifndef FS_INCLUDED 

tinclude <fs.h> 

tendif 

tifndef RESFILE_INCLUDED 
tinclude <resfile.h> 
tendif 

tifndef SWIN_INCLUDED 
tinclude <swin.h> 
tendif 

Common #clefines and iypedefs 



Sort Types 

Defines the order the browser will sort display items by. 

Enumie ( SORT_BY ) { 

browserSortByName = 1, 

browserSortBySize = 2, 

browserSortByDate = 3, 

browserSortByPage = 4, 

browserSortByType = 5 
}; 

These are tags for the icons used by clsBrowser 

tdefine tagBrowserSmallFilelcon MakeTag (clsBrowser,!) 

tdefine tagBrowserBigFilelcon MakeTag (clsBrowser, 2) 

tdefine tagBrowserSmallClosedDirlcon MakeTag (clsBrowser, 3) 

tdefine tagBrowserBigClosedDirlcon MakeTag (clsBrowser, 4) 

tdefine tagBrowserSmallOpenDirlcon MakeTag (clsBrowser, 5) 

tdefine tagBrowserBigOpenDirlcon MakeTag (clsBrowser, 6) 

tdefine tagBrowserSmallClosedSectlcon MakeTag (clsBrowser, 7) 

tdefine tagBrowserBigClosedSectlcon MakeTag (clsBrowser, 8) 

tdefine tagBrowserSmallOpenSectlcon MakeTag (clsBrowser, 9) 

tdefine tagBrowserBigOpenSectlcon MakeTag (clsBrowser, 10) 

tdefine tagBrowserSmallDefaultDocIcon MakeTag (clsBrowser, 11) 

tdefine tagBrowserBigDefaultDocIcon MakeTag (clsBrowser, 12) 



These are the help IDs used for the various browser items. 



tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 



hlpBrowser 

hlpBrowIcon 

hlpBrowName 

hlpBrowPage 

hlpBrowType 

hlpBrowDate 

hlpBrowTime 

hlpBrowSize 

hlpBrowBookmark 

hlpBrowColumn 



MakeTag 
MakeTag 
MakeTag 
MakeTag 
MakeTag 
MakeTag 
MakeTag 
MakeTag 
MakeTag 
MakeTag 



(clsBrowser, 170) 
(clsBrowser, 169) 
(clsBrowser, 171) 
(clsBrowser, 172) 
(clsBrowser, 173) 
(clsBrowser, 174) 
(clsBrowser, 175) 
(clsBrowser, 176) 
(clsBrowser, 177) 
(clsBrowser, 178) 



// Generic TOC 

// TOC 

// TOC 

// TOC 

// TOC 

// TOC 

// TOC 

// TOC 

// TOC 

// TOC 



DskViewer help tags 
tdefine hlpBrowserDV 



MakeTag (clsBrowser, 180) // Generic DSKVIEW 
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♦define hlpBrowNameDV MakeTag(clsBrowser, 181) // DSKVIEW 

♦define hlpBrowTypeDV MakeTag(clsBrowser, 183) // DSKVIEW 

♦define hlpBrowDateDV MakeTag(clsBrowser, 184) // DSKVIEW 

♦define hlpBrowTimeDV MakeTag(clsBrowser, 185) // DSKVIEW 

♦define hlpBrowSizeDV MakeTag(clsBrowser, 186) // DSKVIEW 

Column Tag - identify columns for msgBrowserGesture 

♦define tagBrowNameColumn MakeTag(clsBrowser,191) 

♦define tagBrowPageColumn MakeTag(clsBrowser, 192) 

♦define tagBrowTypeColumn MakeTag(clsBrowser, 193) u, 

♦define tagBrowDateColumn MakeTag(clsBrowser, 194) «a 

♦define tagBrowTimeColumn MakeTag(clsBrowser,195) ^ 

♦define tagBrowSizeColumn MakeTag(clsBrowser, 196) u 

♦define tagBrowBookmarkColumn MakeTag(clsBrowser,197) ^ 

♦define tagBrowUserColumnO MakeTag(clsBrowser, 198) 

♦define tagBrowUserColumnl MakeTag(clsBrowser, 199) 

♦define tagBrowUserColuinn2 MakeTag(clsBroWser,200) 

♦define tagBrowUserColumn3 MakeTag (clsBrowser, 201) 



Messages 



msgNewDefaults: 

Initializes the BROWSER_NEW structure to default values. 

Takes P_BROWSER_NEW, returns STATUS. Category: class message. 

Zeros out pNew->browser. 

msgNew: 

Creates a new browser object. 

Takes P_BROWSER_NEW, returns STATUS. Category: class message. 

typedef struct BROWSER_NEW_ONLY { 

FS_LOCATOR base; // Points to where the browser will display. 

// Note: This UID must not be an absolute path! 

OBJECT client; // UID of client. 

U16 tocView; // TRUE for TOC view, FALSE for disk view. 

U8 spare [8]; 

} BROWSER_NEW_ONLY, *P_BROWSER_NEW_ONLY; 

♦define browserNewFields \ 

scrollWinNewFields \ 

BROWSER_NEW_ONLY browser; 

typedef struct BROWSER_NEW { 

browserNewFields 
} BROWSER_NEW, *P_BROWSER_NEW; 

Comments Creates a browser which will display the file system within the specified base directory. If the browser 

will be looking at "live" notebook sections and documents set tocView to true; If the browser will be 
looking at "dead" directories, files, or documents and sections on disk then set tocView to false. 

msgBrowserCreateDir 

Creates a directory at the selection. 

Takes nothing, returns STATUS. 

♦define msgBrowserCreateDir MakeMsg (clsBrowser, 1) 

Comments If nothing is selected, this message creates a directory at the top level of the disk. DskView message only. 

Usually sent from menu. 
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msgBrowserByName 

Sorts by name order. 
Takes nothing, returns STATUS. 

tdefine msgBrowserByName MakeMsg(clsBrowser, 2) 

:omnient$ Displays all displayed items sorted by name order. Usually sent from menu. 



msgBrowserByType 

Sorts by type order. 

Takes nothing, returns STATUS. 

#define msgBrowserByType MakeMsg(clsBrowser, 40) 

Comments Displays all displayed items sorted by type order. Usually sent from menu. 

msgBrowserBySize 

Sorts by size order. 

Takes nothing, returns STATUS. 

tdefine msgBrowserBySize MakeMsg(clsBrowser, 3) 

Displays all displayed items sorted by size order. Usually sent from menu. 



msgBrowserByDate 

Sorts by date order. 

Takes nothing, returns STATUS. 

tdefine msgBrowserByDate MakeMsg(clsBrowser, 4) 

Displays all displayed items sorted by date order. Usually sent from menu. 

msgBrowserExpand 

Expands sections or directories. 

Takes nothing or P_FS_FLAT_LOCATOR, returns STATUS. 
tdefine msgBrowserExpand MakeMsg(clsBrowser, 5) 

If pArgs is P_FS_FLAT_LOCATOR, expands P_FS_FLAT_LOCATOR otherwise if pArgs is pNull and the 
browser has the selection, the selection is expanded. Otherwise, every displayed closed selection is 
expanded. 

msgBrowserCoUapse 

Collapses sections or directories. 

Takes nothing or P_FS_FLAT_LOCATOR, returns STATUS. 

tdefine msgBrowserCoUapse MakeMsg(clsBrowser, 6) 

€0mmeiits If pArgs is P_FS_FLAT_LOCATOR, collapses P_FS_FLAT_LOCATOR otherwise if pArgs is pNull and the 

browser has the selection, the selection is collapsed; otherwise, every open selection is collapsed. 
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msgBrowserRefresh 

Refreshes the disk image the browser is displaying. 

Takes nothing, returns STATUS. 

tdefine msgBrowserRefresh MakeMsg(clsBrowser, 15) 

msgBrowserDelete ^ 

III 

Deletes selection if pNull or P_FS_FLAT_L0<:AT0R otherwise. S 

Takes nothing or P_FS_FLAT_LOCATOR, returns STATUS. " 

tdefine msgBrowserDelete MakeMsg(clsBrowser, 22) 

Sent to self to allow subclass to override. 

msgBrowserRename 

Renames browser items. 

Takes nothing or P_FS_FLAT_LOCATOR, returns STATUS. 

tdefine msgBrowserRename MakeMsg(clsBrowser, 23) 

Pops up rename dialog box for the selection if pNull; otherwise the item pointed to by 
P FS FLAT LOCATOR is renamed. Sent to self to allow subclass to override. 



msgBrowserConfirmDelete 

Sets a flag whether to confirm deletions within a browser. 

Takes BOOLEAN, returns STATUS. 

tdefine msgBrowserConfirmDelete MakeMsg(clsBrowser, 24) 

msgBrowserExport 

Puts the selection into export mode. 

Takes nothing, returns STATUS. 

tdefine msgBrowserExport MakeMsg(clsBrowser, 118) 

After this message is received by TOC the selected item is highlighted with the copy box. Then if 
notebook item is dragged to the DiskViewer, it will be exported, not copied. The export mode is 
cancelled when the selection is cancelled or the export completes. TOC only. 

msgBrowserByP^e 

Sorts by page number. 

Takes nothing, returns STATUS. 

tdefine msgBrowserByPage MakeMsg(clsBrowser, 25) 

TOC only. 
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msgBrowserWriteState 

Writes the current browser expanded/collapsed state to a file. 

Takes nothing, returns STATUS. 

tdefine msgBrowserWriteState MakeMsg(clsBrowser, 26) 

Comments This message saves the name of each expanded section or directory to a disk file. By using 

msgBrowserSetSaveFile clients or subclasses can set which file this information is stored in. By default 
the state file ends up in the OSThisApp's directory in a file named BROWSTAT. 



msgBrowserReadState 

Reads the browser expanded/collapsed state from a disk file. 

Takes nothing, returns STATUS. 

tdefine msgBrowserReadState MakeMsg(clsBrowser, 27) 

Comments This message restores the state of the browser view of the notebook or file system. By using 

msgBrowserSetSaveFile clients or subclasses can set which file this information is stored in. By default 
the state file ends up in the OSThisApp's dir in a file named browstate. 



msgBrowserSetSaveFile 

Sets the file that the browser will save open/close state to. 

Takes P_FS_LOQVTOR, returns STATUS. 

fdefine msgBrowserSetSaveFile MakeMsg(clsBrowser,148) 



msgBrowserGetMetrics 

Gets browser metrics. 

Takes P_BROWSER_METRICS, returns STATUS. 

#define msgBrowserGetMetrics MakeMsg(clsBrowser, 28) 

SubClass-definable Column Type 

Defines attributes of the subclass definable browser columns. Subclasses can control up to 
browUserColumns (4) columns. 

User Columns are columns of checkboxes or text, that subclasses of clsBrowser can control. The subclass 
can supply the header above the column and whether or not the boxes appear next to sections or 
documents or both. 

User columns are enabled by setting pMetrics->userColumn.showUserColumn. 

The browser sends msgBrowserUserColuinnQueryState to subclasses to determine the initial state of 
the columns. 

When a column is tapped, msgBrowserUserColumnChanged notifies subclasses that the checkbox has 
toggled. 

tdefine browDefaultColumns 7 // Number of default columns, 

tdefine browUserColumns 4 // Maximum number of user columns. 
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Display justifications 

Enumie ( BROW_JUSTIFY ) { 
browserLeft Justify = 0, 
browserRight Justify = 1, 
browserCenter Justify = 2, 
browserUserJustify = 3 

}; 



// Left justification. 

// Right justification. 

// Center justification. 

// Miscellaneous justification, 



User column type 

Enumie ( USER_COLUMN_TYPE ) { 

browserButtonType = 0, 

browserTextType = 1, 

browserUserType = 2 
}; 
typedef struct { 

BROW_JUSTIFY headerJustify; 

BROW_JUSTIFy column Just if y; 

CHAR columnHeader[nameBuf Length] 

} BROWSER_DEF_COLUMN, *P_BROWSER_DEF_COLUMN; 

typedef struct { 



// Button user column. 

// Text user column. 

// User defined user column. 



// Justification of header. 
// Justification of column. 
// Text for column. 



U16 



showUserColumn : 1 ; 



U16 






userColumnOnSections 


U16 






userColumnOnDocs : 1; 


USER_ 


_COLUMN_TYPE 


userColumnType ; 


char" 






userColumnHeader [name 


TAG 






helpTag; 


CHAR 






checkedChar; 


CHAR 






uncheckedChar; 


BROW_ 


JUSTIFY 




headerJustify; 


BROW 


^JUSTIFY 




columnJustify; 


U8 






spare [4] ; 


} BROWSER_COLUMN, 


*P_BROWSER_COLUMN ; 


typedef struct BROWSER 


_METRICS { 


U16 






showlcon : 1; 


U16 






showType : 1; 


U16 






showSize : 1; 


U16 






showDate : 1; 


U16 






showBookmark : 1 ; 


U16 






showHeader : 1; 


U16 






computeRecursiveSize 



U16 

SORT_BY 

BROWSER_COLUMN 
BROWSER_DEF_COLUMN 
U8 



// Must be set to TRUE for the 

// following fields to apply. 
1; // Show userColumn next to sections. 

// Show userColumn next to documents. 

// Type of field if user column. 
ifLength] ; // Text of column header. 

// Tag for quick help 

// Character to show when checked. 

// Character to show when unchecked. 

// Justification of header. 

// Justification of column. 

// Spare: reserved. 



// Show icons. 

// Show type field. 

// Show size field. 

// Show date field. 

// Show bookmark field. (TOC only) 

// Show column header. 
1; // Computes recursive size 

// for directories. 

// TOC does this by default. 

// Show page turn buttons 

// instead of icons. (TOC only) 
sortBy; // Field by which to sort items. 

userColumn [browUserColumns ] ; // Subclass-definable columns 
defaultColumn[browDefaultColumns] ; // Default columns 
spare[40]; // Spare: reserved. 



showIconButton : 1; 



} BROWSER METRICS, *P BROWSER METRICS; 



msgBrowserSetMetrics 



Sets browser metrics. 

Takes P_BROWSER_METRICS, returns STATUS. 

tdefine msgBrowserSetMetrics MakeMsg(clsBrowser, 29) 



Message typedef Struct BROWSER_METRICS { 

krQuments U16 showlcon : 1; 

U16 showType : 1; 

U16 showSize : 1; 



// Show icons. 

// Show type field. 

// Show size field. 
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U16 showDate : 1; // Show date field. 

U16 showBookmark : 1; // Show bookmark field. (TOC only) 

U16 showHeader : 1; // Show column header. 

U16 computeRecursiveSize : 1; // Computes recursive size 

// for directories. 

// TOC does this by default. 
U16 showIconButton : 1; // Show page turn buttons 

// instead of icons. (TOC only) 
SORT_BY sortBy; // Field by which to sort items. 

BROWSER_COLUMN userColumn[browUserColumns] ; // Subclass-definable columns 
BROWSER_DEF_COLUMN defaultColumn [browDefaultColumns] ; // Default columns 
U8 spare [40]; // Spare: reserved. 

} BROWSER_METRICS, *P_BROWSER_METRICS ; 

This message will cause a refresh if userColumn or recursive size become turned on. 

msgBrowserUserColumnGetState 

Does nothing. 

Takes P_BROWSER_USER_COLUMN, returns STATUS. 

#define msgBrowserUserColumnGetState MakeMsg(clsBrowser, 62) 

typedef struct { 

BOOLEAN changed; // TRUE if this column has changed. 

BOOLEAN state; // State of item check box. 

CHAR text [nameBuf Length] ; // Text of field for item. 

BOOLEAN shown; // TRUE if this column is shown. 

// Same as showUserColumn of METRICS. 

BOOLEAN active; // TRUE if this column is active 

// for this browser item. 
} BROWSER_COLUMN_STATE; 

typedef struct { 

FS_FLAT_LOCATOR flat; // Locator of browser item. 

BROWSER_COLUMN_STATE column [browUserColumns] ; // Column information. 

U8 spare[12]; // Spare: reserved. 

} BROWSER_USER_COLUMN, *P_BROWSER_USER_COLUMN; 

msgBrowserUserColumnSetState 

Sets the user column states in the browser for columns that are marked changed. 

Takes P_BROWSER_USER_COLUMN, returns STATUS. 

fdefine msgBrowserUserColumnSetState MakeMsg(clsBrowser, 63) 

typedef struct { 

FS_FLAT_LOCATOR flat; // Locator of browser item. 

BROWSER_COLUMN_STATE column [browUserColumns ] ; // Column information. 

U8 spare[12]; // Spare: reserved. 

} BROWSER_USER_COLUMN, *P_BROWSER_USER_COLUMN; 

If the changed BOOLEAN is set, the user column state will be set. Does not generate a 
msgBrow^serUserColumnStateChanged. The entire BROWSER_USER_COLUMN structure must be 
cleared before setting the fields that are changing. 



msgBrowserUserColumnStateChanged 

Notifies subclass when user checks a user column checkbox. 

Takes P_BROWSER_USER_COLUMN, returns STATUS. 

♦define msgBrowserUserColumnStateChanged MakeMsg{clsBrowser, 68) 



rgument 
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typedef struct { 

FS_FLAT_LOCATOR flat; // Locator of browser item. 

BROWSER_COLUMN_STATE column [browUserColumns] ; // Column information. 

U8 spare[12]; // Spare: reserved. 

} BROWSER_USER_COLUMN, *P_BROWSER_USER_COLUMN; 

The changed field is true for the column that was tapped. 



msgBrowserUserColumnQueiyState 

Gets the user column state from subclass. 

Takes P_BROWSER_USER_COLUMN, returns STATUS. 

tdefine msgBrowserUserColumnQueryState MakeMsg(clsBrowser, 69) 

typedef struct { 

FS_FLAT_LOCATOR flat; // Locator of browser item. 

BROWSER_COLUMN_STATE column [browUserColumns] ; // Column information. 

U8 spare[12]; // Spare: reserved. 

} BROWSER_USER_COLUMN, *P_BROWSER_USER_COLUMN; 

This mess^e is sent to self when the browser needs to know the user column states for a notebook item. 
The FS_FLAT_LOCATOR points to the file system item the browser needs to know the state of The 
subclass should pass back the state or the text of each user column for the file system item. 



msgBrowserShowIcon 

Controls icon field display. 

Takes BOOLEAN, returns STATUS. 

tdefine msgBrowserShowIcon 



MakeMsg(clsBrowser, 100) 



msgBrowserShowButton 

Controls button field display. 
Takes BOOLEAN, returns STATUS. 
#define msgBrowserShowButton 

msgBrowserShowSize 

Controls size field display. 

Takes BOOLEAN, returns STATUS. 

tdefine msgBrowserShowSize 



MakeMsg(clsBrowser, 99) 



MakeMsg(clsBrowser, 102) 



msgBrowserShowDate 

Controls date field display. 

Takes BOOLEAN, returns STATUS. 

tdefine msgBrowserShowDate 

msgBrowserShowType 

Controls type field display. 

Takes BOOLEAN, returns STATUS. 

tdefine msgBrowserShowType 



MakeMsg(clsBrowser, 103) 



MakeMsg(clsBrowser, 33) 
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msgBrowserShowBookmark 

Controls bookmark field display. 

Takes BOOLEAN, returns STATUS. 

♦define msgBrowserShowBookmark MakeMsg(clsBrowser, 104) 

TOCon^. 

msgBrowserShowHeader 

Controls column header display. 

Takes BOOLEAN, returns STATUS. 

#define msgBrowserShowHeader MakeMsg(clsBrowser, 39) 

msgBrowserGoto 

Takes true to goto, false to bringto the selection. 

Takes BOOLEAN, returns STATUS. 

#define msgBrowserGoto MakeMsg(clsBrowser, 105) 

TOC only. Used by menu. 

msgBrowserGotoBringto 

Takes P_BROWSER_GOTO. If pFlat is pNull, applies to selection. 
Takes P_BROWSER_GOTO, returns STATUS. 

tdefine msgBrowserGotoBringto MakeMsg (clsBrowser, 134) 

typedef struct { 

BOOLEAN doGoto; // TRUE - Goto document. 

// FALSE - Bringto document. 
// (Goto if bringto is disabled.) 
FS_FLAT_LOCATOR flat; // Document to goto-bringto . 

} BROWSER_GOTO, *P_BROWSER_GOTO; 

Sent to self to allow subclass to override. TOC only. 

msgBrowserUndo 

Does nothing yet... 

Takes nothing, returns STATUS. 

Idefine msgBrowserUndo MakeMsg (clsBrowser, 106) 

msgBrowserSetSelection 

Causes browser/TOC to select and display the given file system item. 

Takes P_FS_FLAT_LOCATOR, returns STATUS. 

tdefine msgBrowserSetSelection MakeMsg (clsBrowser, 32) 

Jilts As long as the locator points to an item within the browser's base directory subtree, the browser will 

open directories and scroll the display as necessary to display the selected item. 
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msgBrowserSetClient 

Sets the target of the browser dient messages. 
Takes OBJECT, returns STATUS. 

tdefine msgBrowserSetClient MakeMsg(clsBrowser, 108) 

Comments This message controls who gets the various browser client messages. 

msgBrowserGetClient | 

Passes back the target of the browser client messages 

Takes P_OBJECT, returns STATUS. ^ 

tdefine msgBrowserGetClient MakeMsg(clsBrowser, 64) o, 

msgBrowserGetBaseFlatLocator 

Passes back the directory the browser is looking at. 
Takes P_FS_FLAT_LOCATOR, returns STATUS. 

#define msgBrowserGetBaseFlatLocator MakeMsg(clsBrowser, 65) 
Comments Passes back the root directory within which the browser is looking. 

msgBrowserSelectionPath 

Passes back the full path of the selection. 

Takes P_BROWSER_PATH, returns STATUS. 

tdefine msgBrowserSelectionPath MakeMsg(clsBrowser, 109) 

typedef struct { 

CHAR path[fsMaxPathLength]; 
} BROWSER_PATH, *P_BROWSER_PATH; 

Also responds to msgXferGet with id XferFullPathName to get the selections path. Note: If possible use 
msgBrowserSelection with flat locators to avoid duplicate volume name confusion. 

msgBrowserSelection 

Passes back the flat locator of the selection. 
Takes P_FS_FLAT_LOCATOR, returns STATUS. 
tdefine msgBrowserSelection MakeMsg(clsBrowser, 79) 

Commertts Also responds to msgXferGet with id XferFlatLocator to get the selections path. 



msgBrowserSelectionUUID 

Passes back the UUID of the selection. 

Takes P_UUID, returns STATUS. 

tdefine msgBrowserSelectionUUID MakeMsg(clsBrowser, 117) 
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msgBrowserSelectionDir 

Passes back the flat locator of the directory the selection is in. 

Takes P_FS_FLAT_LOCATOR, returns STATUS. 

Idefine msgBrowserSelectionDir MakeMsg(clsBrowser, 110) 

msgBroi?s^serSelectionName 

Returns the name of the selection. 

Takes P_CHAR, returns STATUS. 

tdefine msgBrowserSelectionName MakeMsg(clsBrowser, 111) 

Also responds to msgXferGet with id XferName to get the selections name 

msgBrowserSelectionOn 

Notifies client when a selection is made inside the browser. 

Takes nothing, returns STATUS. 

#define msgBrowserSelectionOn MakeMsg(clsBrowser, 112) 

msgBrowserSelectionOff 

Notifies client when selection is yielded by the browser. 

Takes nothing, returns STATUS. 

#define msgBrowserSelectionOff MakeMsg(clsBrowser,113) 

msgBrowserBookmark 

Notifies client that the bookmark specified by locator has toggled. 

Takes P_BROWSER_BOOKMARK, returns STATUS. 

#define msgBrowserBookmark MakeMsg(clsBrowser, 107) 

typedef struct { 

FS_LOCATOR loc; 
} BROWSER_BOOKMARK, *P_BROWSER_BOOKMARK; 

msgBrowserCreateDoc 

Creates a directory. 

Takes P_BROWSER_CREATE_DOC, returns STATUS. 

fdefine msgBrowserCreateDoc MakeMsg(clsBrowser, 152) 

typedef struct { 



CLASS 


docClass; 


P_CHAR 


pName; 


BOOLEAN 


atSelection; 


XY32 


xy; 



} BROWSER_CREATE_DOC, *P_BROWSER_CREATE_DOC; 

The directory is created at the selection if there is one. If not, the directory is created at the top level 
shown. DiskView oni^. 
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msgBrowserGetBrowWin 

Passes back the browser's internal display window. 

Takes pObject, returns STATUS. 

#define msgBrowserGetBrowWin MakeMsg(clsBrowser,149) 

The browser's internal display window is the selected object for any selection based operations. 



Sends to self gesture and which file it landed on. >. 



msgBrowserGesture § 

Sends to self gesture and which file it landed o 

Takes P_BROWSER_GESTURE, returns STATUS. ^ 

tdefine msgBrowserGesture MakeMsg(clsBrowser,59) o, 

// Gesture that occurred. 
// Item on which to apply the gesture. 
// Original gesture struct. 

// Tag of column on which to apply the gesture. 
// if not on a column. 
// Internal browser information. 
// Spare: reserved. 
} BROWSER_GESTURE, *P_BROWSER_GESTURE; 

Allows subclasses to respond to gestures targeted at browser items. If the status returned by the subclass 
is >= stsOK the gesture will NOT be sent to browser superclass. So subclasses should ignore this message 
or return stsOK to signify it has been handled. 



typedef struct { 
MESSAGE 

P_FS_FLAT_LOCATOR 
P GWIN GESTURE 
TAG 


gesture; 
pFlat; 
pGest; 
columnTag; 


U32 
U32 






info; 
spare [2] ; 
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BYTARRAY.H 



This file contains the API definition for the ByteArray interface. The fiinctions described in this file are 

contained in MISC.LIB. 

A ByteArray implements a growing and shrinking array of bytes, indexed from to 

ByteArrayLength()-l. A ByteArray grabs and releases memory as needed. 

The ByteArray implementation is optimized for highly localized series of insertions and deletions. 

tifndef BYTARRAY_INCLUDED 

♦define BYTARRAY_INCLUDED $Revision: 1.17 $ 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef DEBUG_INCLUDED 

tinclude <debug.h> 

tendif 

tifndef OSHEAP_INCLUDED 

tinclude <osheap.h> 

tendif 



Types and Constants 



typedef struct BYTE_ARRAY * P_BYTE_ARRAY; 
tdefine stsBAMaxExceeded MakeStatus(clsMisc, 255) 
typedef U32 BYTE_INDEX, * P_BYTE_INDEX; 
tdefine SIZE_OF_BYTE_INDEX 4 
tdefine maxBYTE_INDEX maxU32 



Private 



typedef struct BYTE_ARRAY { 

BYTE_INDEX length; 

BYTE_INDEX 

P_U8 

BYTE_INDEX 

P_U8 

U16 
} BYTE ARRAY; 



bufferLength; 

firstPart; 

firstPartLength; 

secondPart; 

mode; 



// Number of bytes stored in buffer 

// Number of bytes in buffer 

// Beginning of the buffer 

// Number of bytes in first part 

// see comments above 

// see comments above 



ByteArrayGapLength 

Returns the size of the byte array's gap. 
Returns BYTEJNDEX. 

tdefine ByteArrayGapLength (p) \ 

( (p) ->buf f erLength - {p)->length) 
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ByteArrayPrint 

Prints the content of the byte array. 
Returns void. 





tifdef DEBUG 
void EXPORTED 




sefi0?i Prototype 


ByteArrayPrint ( 
P BYTE ARRAY 
P_STRING 
int 

#endif // DEBUG 


P. 

charFmt , 
charWidth) ; 



Exported Functions and Macros 

ByteArrayFindByte 

Gets address of byte n from ByteArray p. 

Returns P_U8. 

#define ByteArrayFindByte (p,n) ( \ 

(n) < (p) ->f irstPartLength \ 
? &((p)->firstPart[(n)]) \ 
: & ( (p) ->secondPart [ (n) ] ) ) 

Comnieiifs Warning 1 : n is evaluated twice, so it should not be an expression with an auto-increment or decrement! 

Warning 2: to be as fast as possible, ByteArrayFindByte does no error checking! 

ByteArrayFindlndex 

Determines the index from address addr of byte in ByteArray p. 
Returns BYTEJNDEX. 

#define ByteArrayFindlndex (p, addr) ( \ 

(addr) < &( (p) ->firstPart [ (p) ->f irstPartLength] ) \ 
? (BYTE_INDEX) (addr - (p) ->firstPart) \ 
: (BYTE_INDEX) (addr - (p) ->secondPart) ) 

This is the inverse of ByteArrayFindByte. 

Warnings from ByteArrayFindByte apply here also. 



ByteArrayGetByte 

Get byte n from ByteArray p 

Returns U8. 

#define ByteArrayGetByte (p,n) \ 

( (n) < (p) ->f irstPartLength \ 
? (p) ->firstPart [ (n) ] \ 
: (p) ->secondPart [ (n) ] ) 

Warnings from ByteArrayFindByte apply here also. 
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ByteArrayCreate 

Creates a byte array. 

Returns STATUS. 

STATUS EXPORTED 

Funcfion Profofyi^e ByteArrayCreate ( 

P_BYTE_ARRAY * pp, 
U16 mode, 



«A 



BYTE_INDEX length) ; |5 



Only the osHeapLocal/osHeapShared flags of mode are meaningful. The initial length doesn't matter 
very much, since the byte array grows or shrinks as needed. However, if length is approximately correct, 
then early insertions will be quicker. If length<=0, a length of 1 is assumed. 

Returns stsOK if able to create the byte array, in which case *pp will be the created byte array, otherwise 
*pp will be Nil(P_BYTE_ARRAY). 

The mode parameter is really of type OS_HEAP_MODE. 

ByteArrayDestroy 

Destroys a byte array. 
Returns void, 
void EXPORTED 



iction Prcitofype ByteArrayDestroy ( 

P_BYTE_ARRAY p) ; 



ByteArrayGetMany 

Gets one or more characters from contiguous positions in the byte array. 
Returns STATUS. 

STATUS EXPORTED 



^r«jfo%**l 



ByteArrayGetMany ( 




P_BYTE_ARRAY 


P. 


BYTE_INDEX 


pos, 


P_U8 


buf. 


BYTE INDEX 


bufLen) ; 



Retrieves up to bufLen characters in p from positions [pos..MIN(pos+bufLen,ByteArrayLength(p)). 
Client should insure that buf != Nil(P_U8). Returns count of bytes placed in buf 

ByteArrayReplace 

Replaces zero or more characters in the byte array. 
Returns STATUS. 
STATUS EXPORTED 



mtmn PmU 


jtype 


ByteArrayReplace ( 








P_BYTE_ARRAY 


Pr 






BYTE INDEX 


pos, 






BYTE INDEX 


len, 






P_U8 


buf, 






BYTE INDEX 


bufLen) ; 
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Replaces len characters in p at positions [pos..pos+len) by bufLen cliaracters from buf. Client should 
insure that pos+Ien <= ByteArrayLength(p). 

Returns: 

stsOutOfMem if no memory available, or 

stsBadParam if range [pos.,pos+len) is invalid, or 

stsBAMaxExceeded if the maximum ByteArray length is exceeded, or 

number bytes taken from buf otherwise. 



ByteArraylnsert 

Inserts buflLen characters from buf into p at position pos. 
Returns STATUS. 

fdefine ByteArraylnsert (p, pos, buf, buf Len) \ 
ByteArrayReplace ( (p) , (pos), 0, (buf), (bufLen) ) 

ments This routine does no error checking. Client should insure that: pos <= ByteArrayLength(p). 

See ByteArrayReplace for possible return values. 

ByteArrayDelete 

Delete n characters from p starting at pos. 
Returns void. 

#define ByteArrayDelete (p, pos, len) \ 

(void) ByteArrayReplace ( (p) , (pos), (len), Nil(P_U8), 0) 

ments This routine does no error checking. Client should insure that: pos+len <= ByteArrayLength(p). 

ByteArrayLength 

Returns the number of bytes currently stored in the BYTE_ARRAY. 
Returns BYTE_INDEX. 

#def ine ByteArrayLength (p) ( (p) ->length) 

ByteArrayHeapMode 

Returns the heap mode the BYTE_ARRAY was created with. 
Returns OS_HEAP_MODE. 

tdefine ByteArrayHeapMode (p) ((p)->mode) 



ByteArrayReserve 

Reserves space in byte array (without actually initializing it). 

Returns STATUS. 
STATUS EXPORTED 



jiicfion Prototype ByteArrayReserve ( 

P_BYTE_ARRAY p, 

BYTE_INDEX pos, 

BYTE INDEX len); 
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Comments Reserves len characters in p at position pos, but does not initialize tliem. (The gap is guaranteed to not 

break the reserved range.) CUent should insure that pos <= ByteArrayLength(p). 

Returns: 

stsOutOfMem if no memory available, or 

stsBadParam if pos is invalid, or 

stsBAMaxExceeded if the maximum ByteArray length is exceeded, or 

stsOK otherwise. 

ByteArrayWrite 

Writes the content of the byte array to the specified file. 

Returns STATUS. 

STATUS EXPORTED 

rototype ByteArrayWrite ( 

P_BYTE_ARRAY p, 

OBJECT file) ; 

The file parameter must act like a FILE_HANDLE object. 

ByteArrayRead 

Reads previously saved content of a byte array from the specified file. 

Returns STATUS. 

STATUS EXPORTED 

Foticfion Prototype ByteArrayRead ( 

P_BYTE_ARRAY * pp, 

OBJECT file, 

OS_HEAP_MODE mode) ; 

Comments The file parameter must act like a FILE_HANDLE object. 



BAFUeWriteString 

Debugging utility routine to write a string to a file. 
Returns STATUS. 



#ifdef DEBUG 
STATUS EXPORTED 

Fyncfion Protelype BAFileWriteString { 

OBJECT file, 

P_U8 str) ; 

#endif 



Usefiil when initially writing filing code to insert helpfiil strings into the file and to then skip over the 
strings when reading the file. 

This routine takes an exception if it encounters an error. Also, it will only work with a string whose 
length is MAX_STR_LENGTH or less. 

The file parameter must act like a FILE_HANDLE object. 
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BAFileReadString 

Debugging utility routine to read a string from a file. 
Returns STATUS. 

#ifdef DEBUG 
STATUS EXPORTED 

BAFileReadString ( 

OBJECT file, 

P_U8 str) ; 

#endif 



Comments Useful when initially writing filing code to skip over strings written with BAFileWriteString. 

This routine takes an exception if it encounters an error. Also, it will only work with a string whose 
length is MAX_STR_LENGTH or less. 

The file parameter must act like a FILE_HANDLE object. 



;p:i:ii::if»::ili:il:^f;;j^ 



BYTEBUF.H 



This file contains the API definition for clsByteBuf. 

clsByteBuf inherits firom clsObject. 

clsByteBuf provides a facility to store uninterpreted byte strings. Each object of clsByteBuf stores a 
single buffer. This class provides convenient object filing of the buffer data. Storage for each object's 
buffer is allocated out of the creator's shared process heap using OSHeapBlockAlloc. 

Clients who want to store null terminated strings should use clsString (see strobj.h). 

#ifndef BYTEBUF_INCLUDED 
tdefine BYTEBUF_INCLUDED 

tinclude <go.h> 
tinclude <clsmgr.h> 

typedef OBJECT BYTEBUF, *P_BYTEBUF; 

typedef struct BYTEBUF_DATA { 

U16 bufLen; // In/Out: Length {in bytes) of the pBuf buffer. 

P_U8 pBuf; // In/Out: Object buffer. 
} BYTEBUF DATA, *P BYTEBUF DATA; 



Class Messages 



msgNew 

Creates a new buffer object. 

Takes P_BYTEBUF_NEW, returns STATUS. Category: class message. 

typedef struct BYTEBUF_NEW_ONLY { 

BOOLEAN allowObservers; // In: Send clsByteBuf observer messages 

// to the object's observers? 

BYTEBUF_DATA data; // In/Out: Buffer data. 

} BYTEBUF_NEW_ONLY, *P_BYTEBUF_NEW_ONLY; 

tdefine byteBufNewFields \ 
objectNewFields \ 

BYTEBUF_NEW_ONLY bytebuf; 

typedef struct BYTEBUF_NEW { 

byteBufNewFields 
} BYTEBUF_NEW, *P_BYTEBUF_NEW; 

This message allocates shared heap storage for the specified buffer. 

ailowObservers indicates whether the object will send the clsByteBuf observer messages (See 
msgByteBufChanged). Only clsByteBuf messages are affected by this option. Adding and removing 
observers is not affected by this option. 



msgNewDefaults 

Initializes the BYTEBUF_NEW structure to default values. 

Takes P_BYTEBUF_NEW, returns STATUS. Category: class message. 
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lage typedef struct BYTEBUF_NEW { 

fflients byteBufNewFields 

} BYTEBUF_NEW, *P_BYTEBUF_NEW; 

itienfs Sets 

pNew->bytebuf .allowObservers = true; 
pNew->bytebuf .data.bufLen = 0; 
pNew->bytebuf . data . pBuf = pNull; 

allowObservers indicates whether the object will send the clsByteBuf observer messages. (See 
msgByteBuJPChanged) 



Object Messages 



msgByteBuJPGetBuf 

Passes back the object's buffer. 

Takes P_BYTEBUF_DATA, returns STATUS. 

tdefine msgByteBufGetBuf MakeMsg (clsByteBuf , 1) 

age typedef struct BYTEBUF_DATA { 

ment& U16 bufLen; // In/Out: Length (in bytes) of the pBuf buffer. 

P_U8 pBuf; // In/Out: Object buffer. 

} BYTEBUF_DATA, *P_BYTEBUF_DATA; 

tients The pointer passed back references the object's global storage. Clients must not modify or free this 

storage. 



msgByteBu£SetBuf 

Copies the specified buffer data into the object's buffer. 

Takes P_BYTEBUF_DATA, returns STATUS. 

tdefine msgByteBufSetBuf MakeMsg (clsByteBuf, 2) 

typedef struct BYTEBUF__DATA { 

U16 bufLen; // In/Out: Length (in bytes) of the pBuf buffer. 

P_U8 pBuf; // In/Out: Object buffer. 

} BYTEBUF_DATA, *P_BYTEBUF_DATA; 

Previously retrieved bytebuf pointers will be invalid after this operation. Clients must call 
msgByteBuFGetBuf to retrieve a pointer to the valid object buffer. 



Observer Messages 



msgByteBufOhanged 

Sent to observers when the object data changes. 
Takes OBJECT, returns nothing. Category: observer notification. 
#define msgByteBuf Changed MakeMsg (clsByteBuf, 3) 

:omsiients The message argument is the UID of the clsByteBuf object that changed. 

This message is not sent if the creator did not specify allowObservers during msgNew. 






DSKVIEW.H 



This file contains the API definition for clsDiskViewWin. 
clsDiskViewWin inherits from clsCustomLayout. 

It is the view window for a muki-volume disk viewer. 



Overvievsf 

The Disk Viewer also defines clsDVBrowBar, clsDVTabButton, clsDVIcon, and clsDVForward. These 
are internal classes which must be well-known uids, since the Disk Viewer component is shared. 

The Disk Viewer component implements the heart of the Disk Manager. It is consists of two panels: an 
icon panel and a browser panel. Each known filesystem volume (connected and disconnected) is 
represented by an icon in the icon window. Each open volume is represented by a browser card in the 
browser panel. A browser card is a frame with a menu bar and control tab as decoration and an instance 
of clsBrowser in the view (see browser.h for details). 

The icon panel is only as big as it needs to be to fit the known volumes. The browser panel takes up the 
rest of the space. The open browser cards equally divide up the browser panel. 

Clients will typically put the Disk Viewer component inside of a frame. The frame must not be 
shrink-wrapped; the Disk Viewer must be told what size it should be. 

clsDiskViewWin understands the following clsBrowser's messages: 

msgBrowserCreateDir 

The browser messages that deal with the selection are sent to the browser which has the current 
selection. Messages that do not deal with the selection or make sense if there is no selection are sent to 
all browsers in the Disk Viewer. 

The Disk Viewer client is made the client of all the open browsers. The client will get all the messages 
that browsers send to their clients. 

The Disk Viewer takes care of setting up browser state files in a directory off the current working 
directory. The Disk Viewer ensures that the state files for each volume is unique; it handles duplicate 
volume names. 

The Disk Viewer understands msgSave and msgRestore. It will reopen volumes that were open when it 
was saved, and restore as much volume state (which directories were expanded) as possible. 

tifndef DSKVIEW_INCLUDED 
♦define DSKVIEW_INCLUDED 

tifndef CLAyOUT_INCLUDED 
#include <clayout.h> 
#endif 

fifndef BROWSER_INCLUDED 
♦include <browser.h> 
tendif 
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Common #defines and typedefs 



Illegal volume name error. 

#define stsDVIllegalVolumeName MakeStatus (clsDiskViewWin, 0) 

Directory where state files go, relative to theWbrkingDir. 

♦define pDVStateDir "diskViewState" 

Trigger point for going over to 'K' size notation 

tdefine dvKSizeUnit 1024 



Icon Panel Style 



tdefine dvShowIcons 
tdefine dvShowHelpText 

tdefine dvShowClientWin 



// Show icons. 

1 // Show informative message about each 
// view category. 

2 // Client sets contents via 
// msgDVSetlconPanel. 



Icon Style 



tdefine dvBigPictTitleUnder 

tdefine dvBigPictTitleRight 1 

tdefine dvSmallPictTitleUnder 2 

tdefine dvSmallPictTitleRight 3 



// Big icon, title under picture. 

// Big icon, title to right of picture. 

// Small icon, title under picture. 

// Small icon, title to right of picture. 



Disk Vie>ver Style 



typedef struct DV_STYLE { 



U16 


di splayRamVo lume 


1, 


// 
// 




autoOpen 


1, 


// 




enableBookshelf 


1, 


// 




enableDirectoryView : 


1,// 




showVolumeMenu 


1, 


// 




showEditMenu 


1, 


// 




showViewMenu 


1, 


// 




s howOpt ion sMenu 


1, 


// 




iconPanelStyle 


3, 


// 




iconStyle 


3, 


// 
// 




unusedl 


2; 




U16 


spare 1; 






U16 


spare2 ; 






} DV_STYLE, *P DV STYLE; 







Display the RAM volume. Used for debugging, 
Disk Viewer app sets this if /DB0800 is on. 
If there is only one volume, open it. 
Should bookshelf viewing be enabled? 
Should the directory view be enabled? 
Should the volume menu be shown? 
Should the edit menu be shown? 
Should the view menu be shown? 
Should the options menu be shown? 
What should be shown in the icon panel? 
Initial icon look, only used if 
iconPanelStyle == dvShowIcons. 



Array Element For Volume Name Array 

typedef struct NAME { 

U8 pName[nameBufLength] ; 
} NAME, *P_NAME; 

typedef struct DV NEW ONLY { 



DV_STYLE 
P_STRING 

OBJECT 



style; 
pBasePath; 

client; 



U16 


numOpenVols; 


P_NAME 


pOpenVols; 


TAG 


displayType; 



// Path offset for each volume; 

// pNull for no offset. 

// Client. Note: client is *not* saved at 

// msgSave time. Client must restore with 

// msgBrowserSetClient . 

// Number of volumes to pre-open. 

// Array of volume names. 

// Default display type for new cards. 
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CLASS 



CLASS 



browserClass; 



bookshelf Class; 



U8 spare [24]; 
} DV_NEW_ONLY, *P_DV_NEW_ONLY; 

♦define diskViewWinNewFields 
customLayoutNewFields 



// Class of browser to mutate volume 

// default browsers to. objNull says 

// no mutation. 

// Class of bookshelf viewer to mutate 

// volume default bookshelf viewers. 

// objNull says no mutation. 

// Spare: reserved. 



DV NEW ONLY 



diskViewWin; 



typedef struct DV_NEW { 

diskViewWinNewFields 
} DV NEW, *P DV NEW; 



Messages 



msgNew 

Creates a new disk view window. 

Takes P_DV_NEW, returns STATUS. Category: class message. 

typedef struct DV_NEW { 

diskViewWinNewFields 
} DV_NEW, *P_DV_NEW; 

msgNewDefaults 

Initializes the DV_NEW structure to default values. 

Takes P_DV_NEW, returns STATUS. Category: class message. 

typedef struct DV_NEW { 

diskViewWinNewFields 
} DV_NEW, *P_DV_NEW; 

Zeroes out diskViewWin and sets 

diskViewWin . style . displayRamVolume = false; 
diskViewWin. style. autoOpen = false; 
diskViewWin . style . iconStyle = dvBigPictTitleUnder; 
diskViewWin. style. enableBookshelf = true; 
diskViewWin. style. enableDirectoryView = true; 
diskViewWin. style. showVolumeMenu = true; 
diskViewWin . style . showEditMenu = true; 
diskViewWin . style . showViewMenu = true; 
diskViewWin. style. showOptionsMenu = true; 
diskViewWin. style. iconPanelStyle = dvShowIcons; 
diskViewWin. numOpenVols = 0; 
diskViewWin. displayType = tagDWiewBookshelf ; 
diskViewWin. browserClass = objNull; 
diskViewWin. bookshelf Class = objNull; 



msgDVGetStyle 

Gets current style setting. 

Takes P_DV_STYLE, returns STATUS. 

tdefine msgDVGetStyle 



MakeMsg(clsDiskViewWin, 1) 
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5«ge typedef struct DV STYLE { 



U16 


di splayRamVolume 


1, 


// 
// 




autoOpen 


1, 


// 




enableBookshelf 


1, 


// 




enableDirectoryView : 


1,11 




showVolumeMenu 


1, 


II 




showEditMenu 


1, 


II 




showViewMenu 


1, 


II 




showOptionsMenu 


1, 


II 




iconPanelStyle 


3, 


II 




iconStyle 


3, 


II 

n 




unusedl 


2; 




U16 


sparel; 






U16 


spare2 ; 






} DV STYLE, *P DV STYLE; 







Display the RAM volume. Used for debugging. 
Disk Viewer app sets this if /DB0800 is on. 
If there is only one volume, open it. 
Should bookshelf viewing be enabled? 
Should the directory view be enabled? 
Should the volume menu be shown? 
Should the edit menu be shown? 
Should the view menu be shown? 
Should the options menu be shown? 
What should be shown in the icon panel? 
Initial icon look, only used if 
iconPanelStyle == dvShowIcons. 



msgDVSetStyle 

Sets style setting. 

Takes P_DV_STYLE, returns STATUS. 
#define msgDVSetStyle 
typedef struct DV STYLE { 



U16 


di splayRamVolume : 


1, 


// 
// 




autoOpen : 


1, 


// 




enableBookshelf : 


1, 


// 




enableDirectoryView : 


1,// 




showVolumeMenu : 


1, 


// 




ShowEditMenu 


1, 


// 




showViewMenu 


1, 


// 




showOptionsMenu : 


1, 


// 




iconPanelStyle : 


3, 


// 




iconStyle : 


3, 


// 
// 




unusedl : 


2; 




U16 


sparel; 






U16 


spare2 ; 






} DV STYLE, *P DV STYLE; 







MakeMsg(clsDiskViewWin, 2) 

Display the RAM volume. Used for debugging. 
Disk Viewer app sets this if /DB0800 is on. 
If there is only one volume, open it. 
Should bookshelf viewing be enabled? 
Should the directory view be enabled? 
Should the volume menu be shown? 
Should the edit menu be shown? 
Should the view menu be shown? 
Should the options menu be shown? 
What should be shown in the icon panel? 
Initial icon look, only used if 
iconPanelStyle == dvShowIcons. 



msgDVGetBasePath 

Passes back the current base path. 

Takes P_STRING, returns STATUS. 

tdefine msgDVGetBasePath MakeMsg(clsDiskViewWin, 3) 

The argument must point to a string buffer that is at least fsPathBufLength in size. 



msgDVGetlconPanel 

Passes back the current icon panel w^indow. 
Takes P_WIN, returns STATUS. 
♦define msgDVGetlconPanel 



MakeMsg(clsDiskViewWin, 4) 
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msgDVSetlconPanel 

Sets the icon panel window. 
Takes P_WIN, returns STATUS. 

tdefine msgDVSetlconPanel MakeMsg(clsDiskViewWin, 5) 

Zcmmenfs This message is only relevant if style.iconPanelStyle is set to dvShowHelpText or dvShowClientWin. 

msgDVGetOpenVols 

Passes back the names of all the currently open volumes. 

Takes P_DV_GET_OPEN_VOLS, returns STATUS. 

tdefine msgDVGetOpenVols MakeMsg(clsDiskViewWin, 7) 

Irgumenfs typedef Struct DV_GET_OPEN_VOLS { 

U16 numOpenVols; // Number of open volumes. 

P_NAME pOpenVols; // Out: Array of volume names. 

// must be OSHeapBlockFreed. 
U8 spare [24]; 

} DV_GET_OPEN_VOLS, *P_DV_GET_OPEN_VOLS ; 

:o5time?its This message allocates a heap block on the process local stack (pOpenVols). THE CALLER MUST 

FREE THIS BLOCK WHEN DONE. 

If there are no open volumes then pOpenVols is set to pNull and nothing is allocated. 

F Private 

msgDVSetOptionVolume 

Sets the current volume for our option sheet. 

Takes OBJECT, returns STATUS. 

tdefine msgDVSetOptionVolume MakeMsg(clsDiskViewWin, 8) 

msgDVCardPopupChanged 

Option card's quick installer popup button has changed. 

Takes BOOLEAN, returns STATUS. 

tdefine msgDVCardPopupChanged MakeMsg(clsDiskViewWin, 9) 

msgDVOptionMenuNeed 

Sent to the disk view client as notification that the option menu is being provided. 

Takes nothing, returns STATUS. 

#define msgDVOptionMenuNeed MakeMsg(clsDiskViewWin, 10) 



msgDVOpenVolume 

Opens the disk browser of the volume specified by the given name. 

Takes P_CHAR, returns STATUS. 

♦define msgDVOpenVolume MakeMsg(clsDiskViewWin, 11) 
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msgDVCloseVolume 

Closes the disk browser of the volume specified by the given name. 

Takes P_CHAR, returns STATUS. 

♦define msgDVCloseVolume MakeMsg(clsDiskViewWin, 12) 

msgDVConnectToVolume 

Connects a network volume specified in pArgs. 

Takes P_CONNECTIONS_MENU_ITEM, returns STATUS. 

tdefine msgDVConnectToVolume MakeMsg(clsDiskViewWin, 13) 



Menu Messages 



♦define msgDVOpenClose 
tdefine msgDVDuplicate 
tdefine msgDVAddQuicklnstall 
tdefine msgDVRemoveQuicklnstall 
#define msgDVEjectRemember 
tdefine msgDVEjectForget 
tdefine msgDVFormat 
tdefine msgDVRename 

tdefine msgDWiewAll 
tdefine msgDWiewBookshelf 
tdefine msgDVDisplaylnstaller 

tdefine msgDVLayoutOptions 
tdefine msgDVDiskOptions 

tdefine msgDVOpt ions Icon 
tdefine msgDVOpt ions Type 
tdefine msgDVOptionsDate 
tdefine msgDVOptionsSize 
tdefine msgDVOptionsDirSize 
tdefine msgDVOptionsVersion 
tdefine msgDVOptionsInstall 

tdefine msgDVSortByName 
tdefine msgDVSortByDate 
tdefine msgDVSortBySize 
tdefine msgDVSortByType 

// Note: clsDVForward messages 100 



MakeMsg(clsDVForward, 1) 

MakeMsg (clsDVForward, 2) 

MakeMsg (clsDVForward, 3) 

MakeMsg (clsDVForward, 4) 

MakeMsg (clsDVForward, 5) 

MakeMsg (clsDVForward, 6) 

MakeMsg (clsDVForward, 7) 

MakeMsg (clsDVForward, 10) 

MakeMsg (clsDVForward, 20) 

MakeMsg (clsDVForward, 21) 

MakeMsg (clsDVForward, 22) 

MakeMsg (clsDVForward, 30) 

MakeMsg (clsDVForward, 31) 

MakeMsg (clsDVForward, 41) 

MakeMsg (clsDVForward, 42 ) 

MakeMsg (clsDVForward, 43) 

MakeMsg (clsDVForward, 44 ) 

MakeMsg (clsDVForward, 45) 

MakeMsg (clsDVForward, 46) 

MakeMsg (clsDVForward, 47) 

MakeMsg (clsDVForward, 50) 

MakeMsg (clsDVForward, 51) 

MakeMsg (clsDVForward, 52) 

MakeMsg (clsDVForward, 53) 

and above are used internally. 



Tags 



tdefine tagDWolumeMenu 
tdefine tagDVEditMenu 
tdefine tagDWiewMenu 
tdefine tagDVOptionsMenu 

tdefine tagDVTabButton 

tdefine tagDVOpenClose 
tdefine tagDVDuplicate 
tdefine tagDVEjectRemember 
tdefine tagDVEjectForget 
tdefine tagDVRefresh 
tdefine tagDVQuicklnstall 
tdefine tagDVFormat 
tdefine tagDVRename 
tdefine tagDVCreateDir 

tdefine tagDWiewChoice 



MakeTag(clsDiskViewWin, 1) 

MakeTag(clsDiskViewWin, 2) 

MakeTag(clsDiskViewWin, 3) 

MakeTag(clsDiskViewWin, 4) 

MakeTag(clsDiskViewWin, 7) 

MakeTag(clsDiskViewWin, 10) 

MakeTag(clsDiskViewWin, 11) 

MakeTag(clsDiskViewWin, 12) 

MakeTag(clsDiskViewWin, 13) 

MakeTag(clsDiskViewWin, 14) 

MakeTag(clsDiskViewWin, 15) 

MakeTag(clsDiskViewWin, 16) 

MakeTag(clsDiskViewWin, 17) 

MakeTag(clsDiskViewWin, 18) 

MakeTag(clsDiskViewWin, 20) 



tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 

tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 
tdefine 
tdefine 

tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
tdefine 
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Tags 


tagDWiewAll 


MakeTag (clsDiskViewWin, 
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tagDWiewBookshelf 


MakeTag (clsDiskViewWin, 


22) 




tagDVExpand 


MakeTag (clsDiskViewWin, 


23) 




tagDVCollapse 


MakeTag (clsDiskViewWin, 


24) 




tagDVLayoutOptionMenu 


MakeTag (clsDiskViewWin, 


25) 




tagDVDiskOptionMenu 


MakeTag (clsDiskViewWin, 


26) 




tagDVColumnLayoutOptions 


MakeTag (clsDiskViewWin, 


30) 




tagDVBookshelfLayoutOptions 


MakeTag (clsDiskViewWin 


31) 




t agDVD i s k I conOpt ions 


MakeTag (clsDiskViewWin, 


32) 




tagDVDiskOptions 


MakeTag (clsDiskViewWin, 


33) 




tagDVOptionsIcon 


MakeTag (clsDiskViewWin, 


40) 




tagDVOptionsType 


MakeTag (clsDiskViewWin, 


41) 




tagDVOptionsSize 


MakeTag (clsDiskViewWin 


42) 




tagDVOptionsDirSize 


MakeTag (clsDiskViewWin 


43) 




tagDVOptionsDate 


MakeTag (clsDiskViewWin 


44) 




tagDVOpt ions Vers ion 


MakeTag (clsDiskViewWin 


45) 




tagDVOptionsInstall 


MakeTag (clsDiskViewWin 


46) 




tagDVSortByChoice 


MakeTag (clsDiskViewWin, 


50) 




tagDVSortByName 


MakeTag (clsDiskViewWin 
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tagDVSortByDate 


MakeTag (clsDiskViewWin 


52) 




tagDVSortBySize 


MakeTag (clsDiskViewWin 


53) 




tagDVSortByType 


MakeTag (ClsDiskViewWin 


54) 




tagDVIconCard 


MakeTag (ClsDiskViewWin 


60) 




tagDVIconLabel 


MakeTag (clsDiskViewWin 


61) 




tagDVIconChoice 


MakeTag (clsDiskViewWin 


62) 




tagDVIconBigPictTitleUnder 


MakeTag (clsDiskViewWin 


63) 




tagDVIconBigPictTitleRight 


MakeTag (clsDiskViewWin 


64) 




tagDVIconSmallPictTitleUnder 


MakeTag (clsDiskViewWin 


65) 




tagDVIconSmallPictTitleRight 


MakeTag (clsDiskViewWin 


66) 




tagDVDefaultBigBitmap 


MakeTag (clsDiskViewWin 


67) 




tagDVDe fault SmallBitmap 


MakeTag (clsDiskViewWin 


68) 




tagDVCardName 


MakeTag (clsDiskViewWin 


70) 




tagDVCardTotal 


MakeTag (clsDiskViewWin 


71) 




tagDVCardFree 


MakeTag (clsDiskViewWin 


72) 




tagDVCardReadOnly 


MakeTag (clsDiskViewWin 


73) 




tagDVCardPopupViewer 


MakeTag (clsDiskViewWin 


74) 




tagDVCardPopupYes 


MakeTag (clsDiskViewWin 


75) 




tagDVCardPopupNo 


MakeTag (clsDiskViewWin 


76) 




tagDVCardlnitialView 


MakeTag (clsDiskViewWin 


77) 




tagDVCardlnitialPopupChoice 


MakeTag (clsDiskViewWin 


78) 




tagDVBookshelfLayoutLabel 


MakeTag (clsDiskViewWin 


80) 




tagDVBookshelfLayoutChoice 


MakeTag (clsDiskViewWin 


81) 




hlpDVNoVol;mesConnected 


MakeTag (clsDiskViewWin 
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hlpDVSheetBackground 


MakeTag (clsDiskViewWin 


101) 




hlpDVIcon 


MakeTag (clsDiskViewWin 


102) 




hlpDVI conBackgr ound 


MakeTag (clsDiskViewWin 


103) 




hlpDVTabButton 


MakeTag (clsDiskViewWin 


104) 




hlpD Wo lumeMenu 


MakeTag (clsDiskViewWin 


110) 




hlpDVEditMenu 


MakeTag (clsDiskViewWin 


111) 




hlpDWiewMenu 


MakeTag (clsDiskViewWin 


112) 




hlpDVOptionsMenu 


MakeTag (clsDiskViewWin 


113) 




hlpDVClose 


MakeTag (clsDiskViewWin 


120) 




hlpDVDuplicate 


MakeTag (clsDiskViewWin 


121) 




hlpDVE j ect Remembe r 


MakeTag (clsDiskViewWin 


r 122) 




hlpDVEjectForget 


MakeTag (clsDiskViewWin 


, 123) 




hlpDVRefresh 


MakeTag (clsDiskViewWin 


124) 




hlpDVQuicklnstall 


MakeTag (clsDiskViewWin 


, 125) 




hlpDVFormat 


MakeTag (clsDiskViewWin 


r 126) 
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tdefine hlpDVMove 
♦define hlpDVCopy 
tdefine hlpDVDelete 
tdefine hlpDVRename 
tdefine hlpDVCreateDir 

tdefine hlpDWiewAll 
tdefine hlpDWiewBookshelf 
tdefine hlpDVDisplaylnstaller 
tdefine hlpDVExpand 
tdefine hlpDVCollapse 

tdefine hlpDVLayoutOptionMenu 
tdefine hlpDVDiskOptionMenu 
tdefine hlpDVDiskOptions 
tdefine hlpDVDisklconOptions 
tdefine hlpDVColumnLayoutOptions 
tdefine hlpDVBookshelfLayoutOptions 

tdefine hlpDVOptionsColumnsLabel 
tdefine hlpDVOptionsIcon 
tdefine hlpDVOptionsType 
tdefine hlpDVOptionsDate 
tdefine hlpDVOptionsSize 
tdefine hlpDVOptionsDirSize 
tdefine hlpDVOptionsVersion 
tdefine hlpDVOptionsInstall 
tdefine hlpDVSortByChoice 
tdefine hlpDVSortByName 
tdefine hlpDVSortByDate 
tdefine hlpDVSortBySize 
tdefine hlpDVSortByType 
tdefine hlpDVDiskCardName 
tdefine hlpDVDiskCardTotalSpace 
tdefine hlpDVDiskCardFreeSpace 
tdefine hlpDVDiskCardReadOnly 
tdefine hlpDVDiskCardQuicklnstaller 
tdefine hlpDVDiskCardlnitialView 

tdefine hlpDVIconCardStyle 

// QH tags for the column headers in 
tdefine hlpDVNameColumn 
tdefine hlpDVTypeColumn 
tdefine hlpDVDateColumn 
tdefine hlpDVTimeColumn 
tdefine hlpDVSizeColumn 
tdefine hlpDWersionColumn 
tdefine hlpDVInstallColumn 



MakeTag(clsDiskViewWin, 130) 

MakeTag(clsDiskViewWin, 131) 

MakeTaglclsDiskViewWin, 132) 

MakeTaglclsDiskViewWin, 133) 

MakeTag(clsDiskViewWin, 134) 

MakeTag(clsDiskViewWin, 140) 

MakeTag(clsDiskViewWin, 141) 

MakeTag(clsDiskViewWin, 142) 

MakeTag(clsDiskViewWin, 143) 

MakeTag(clsDiskViewWin, 144) 

MakeTag(clsDiskViewWin, 145) 

MakeTag{clsDiskViewWin, 146) 

tagDVDiskOptions 
tagDVDi ski conOpt ions 
tagDVColumnLayoutOptions 
tagDVBookshelfLayoutOptions 



MakeTag (clsDiskViewWin 


150) 


MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (ClsDiskViewWin 
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MakeTag (ClsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 


172) 


MakeTag (ClsDiskViewWin 
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MakeTag (ClsDiskViewWin 
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MakeTag (ClsDiskViewWin 
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MakeTag (ClsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 


184) 


MakeTag (clsDiskViewWin 


185) 


MakeTag (clsDiskViewWin 


190) 


diskview 




MakeTag (clsDiskViewWin 
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MakeTag (clsDiskViewWin 


192) 


MakeTag (clsDiskViewWin 


193) 


MakeTag (clsDiskViewWin 


194) 


MakeTag (clsDiskViewWin 


195) 


MakeTag (clsDiskViewWin 


196) 


MakeTag (clsDiskViewWin 


197) 









EXPORT.H 



This file contains tiie API definition for clsExport. 

clsExport inherits from clsObject. 

clsExport is the abstract class defining the API for exporting data to external disks. 

The clsExport API provides a common mechanism for documents to translate themselves into foreign 
file formats and place the file on external disks. 

Overvievs^ 

The export protocol is initiated from the move/copy protocol (see embedwin.h). All moves/copies from 
the TOC to non-bookshelf views of the DiskViewer are implicitly exports. 

More specificalfy^, export happens afi;er msgSelCopySeiection reaches the DiskViewer, which is the 
destination of the copy, and the source of the copy includes clsExport as an item in the list returned by 
msgXferList. Anything moveable/copyable can potentially invoke export. (See xfer.h and sel.h for 
information on PenPoint's move/copy protocol and selection management.) 

The DiskViewer will send the source of the copy (the selection) msgExportGetFormats. The source 
should pass back an array of possible export formats. From the information in msgExportGetFormats 
cisApp generates the export dialog box. If the user selects the external export format and taps the 
Move/Copy button, the export class sends msgExport to the appropriate translator specified in 
msgExportGetFormats. If user selects the PenPoint format and taps the Move/ Copy button, the 
move/ copy is equivalent to msgAppMgrMove/msgAppMgrCopy (see appmgr.h). 

If the source of the export is in the TOC, the DiskViewer activates the source document and sends it 
msgExportGetFormats. 

Hovsf to Be an Exporting Application 

Any application that wants to export must have its subclass of clsApp respond to msgExportGetFormats 
and msgExport. 

tifndef EXPORT_INCLUDED 

tdefine EXPORT_INCLUDED 

tifndef GO_INCLUDED 

tinclude <go.h> 

#endif 

tifndef UID_INCLUDED 

tinclude <uid.h> 

tendif 

tifndef FS_INCLUDED 

tinclude <fs.h> 

tendif 
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Common #defines and typedefs 



Status codes 



#define stsExportActivateSource 

#define stsExportFailed 

#define stsExportFailedUserNotified 



MakeWarning(clsExport, 1) 
MakeWarning(clsExport, 2) 
MakeWarning(clsExport, 3) 



Messages 



Comeicjits 



msgExportGetFormats 

Passes back the export format array from from the source of the export. 
Takes P_EXPORT_LIST, returns STATUS. Category: cHent responsibility. 
#define msgExportGetFormats MakeMsg(clsExport, 1) 



typedef struct { 

TAG document Type ; 

TAG export Type; 

OBJECT translator; 

CHAR exportName[nameBufLength] 



// Source document type. 

// Export destination type. 

// Object which to send msgExport. 

// Name of export type for 

// display in dialog box. 



} EXPORT_FORMAT, *P_EXPORT_FORMAT ; 

typedef struct { 

P_EXPORT_FORMAT format; 

U16 numEntries; 

} EXPORT LIST, *P EXPORT LIST; 



// Array of formats, must be SHARED 

// memory, freed by caller. 

// Number of elements in format array. 



The DiskViewer sends this message to the selection. 

The recipient should allocate global memory to hold the EXPORT_FORMAT array which is passed back 
to the DiskViewer in the format field. The sender of msgExportGetFormats must free the memory. 

If the source returns stsExportActivateSource, the DiskViewer will treat the source as an inactive 
document (This is how the TOC behaves when it is the source of export). The source will be activated 
using msgAppMgrActivate and the activated doc will be sent msgExportGetFormats. 

msgExport 

Initiates export by the translator. 

Takes P_EXPORT_DOC, returns STATUS. Category: client responsibility. 

#define msgExport MakeMsg{clsExport, 2) 



typedef struct { 
TAG 

FS_LOCATOR 

FILE HANDLE 



CHAR 
TAG 

U32 
U32 



export Type; 



source; 



destination; 



path [fsPathBuf Length] ; 
document Type; 

sparel ; 
spare2 ; 



// Corresponds to export Type from 

// msgExportGetFormats EXPORT_FORMAT . 

// Source document or null if 

// source is not a document. 

// Destination file handle. 

// If you don't want to export to 

// this file, use msgFSGetPath to 

// retrieve the destination and 

// destroy this file handle. 

// Source path. 

// Corresponds to document Type from 

// msgExportGetFormats EXPORT_FORMAT . 

// Spare: reserved 

// Spare: reserved 



} EXPORT DOC, *P EXPORT DOC; 
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Miscellaneous 

Comments This message is sent to the translator specified in EXPORT_FORMAT. The translator is passed an open file 

handle to which the translator can write exported data or the translator can get the path of the file, 
destroy the file and replace it with its own file structure. 

If the export fails, it is the exporter's reponsibility for removing invalid and/or partial files created during 
the failed export. The minimum the client should do is send msgFSDelete to pArgs->destination to 
remove the file created for the exportation. 

If the exporter wishes to put their custom dialog box to query the user for more information, the 

exporter should do this in response to msgExport. If the custom dialog allows the user to cancel the 

export operation, then the exporter should return stsExportFailedUserNotified which will cause B 

PenPoint to suppress any error of the aborted export. 



TAG 


document Type, • 


TAG 


exportType; 


OBJECT 


translator; 


CHAR 


exportName [nameBuf Length] ; 



«/) 



>- 



3 



msgExportName <> 

Passes back a possibly modified destination name from the translator. 

Takes P_EXPORT_FORMAT, returns STATUS. 

tdefine msgExportName MakeMsg(clsExport, 3) 

typedef struct { 

// Source document type. 

// Export destination type. 

// Object which to send msgExport. 

// Name of export type for 

// display in dialog box. 
} EXPORT_FORMAT, *P_EXPORT_FORMAT; 

Comments This message is sent to the translator specified in EXPORT_FORMATS whenever the user chooses a new 

export type in the dialog box. When the translator receives the message, export name is set to the source 
document name. The translator should set export name exportName should be set to the "correct" 
destination file name. For instance the extension '.RTF' or '.WKS' may be appended to the name. 

If the translator ignores this message the destination name will remain unchanged (so this message can 
safely be ignored). 

^ Miscellaneous 
^ Help tags 

These are help tags on various pieces of the standard export dialog box. 

tdefine hlpExportSheet MakeTag(clsExport, 50) 

tdefine hlpExportName MakeTag(clsExport, 51) 

tdefine hlpExportNewName MakeTag(clsExport, 52) 

tdefine hlpExportChoice MakeTag(clsExport, 53) 
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GMARGIN.H 



This file contains the API definition for clsGestureMargin. 
clsGestureMargin inherits from clsScrollWin. 

clsGestureMargin adds a margin to the scroll win on the opposite side from the scroll bar. Gestures 

made in the margin are forwarded to the client win. 

clsGestureMargin is used in PenPoint by the MiniNote application. MiniNote uses the gesture margin 

in lieu of a scroll win. When MiniNote is in writing mode, the margin is gray. In gesture mode, the 

margin is white. 

Gesture mode is intended to indicate a "safe" mode in which the 1 1 core gestures can be used. In ink 

mode, some gestures do not work and be may interpreted as some other type of data (e.g. ink). 

#ifndef GMARGIN_INCLUDED 
#define GMARGIN_INCLUDED 
tifndef SWIN_INCLUDED 
♦include <swin.h> 
tendif 



Types and Constants 



♦define clsGestureMargin MakeGlobalWKN (2572,1) 

♦define clsGestureMarginlnnerWin MakeGlobalWKN (2573, 1) 
typedef struct GESTURE_MARGIN_STYLE { 



U16 gestureMargin : 1, 
wideGestureMargin : 1, 



maskGestureMargin : 1, 
inkMode : 1 , 

reserved :12; 

} GESTURE_MARGIN_STYLE, *P_GESTURE_MARGIN_STYLE; 

typedef struct { 

GESTURE_MARGIN_STYLE Style; 

S32 spares [4 ]; 

} GESTURE_MARGIN_NEW_ONLY, *P_GESTURE_MARGIN_NEW_ONLY; 

♦define gestureMarginNewFields \ 
scrollWinNewFields \ 
GESTURE_MARGIN_NEW_ONLY gestureMargin ; 

typedef struct { 

gestureMarginNewFields 
} GESTURE MARGIN NEW, *P_GESTURE_MARGIN_NEW; 



// gesture margin on/off 

// make the gesture margin wide 

// (not implemented) 

// mask out gestureMargin 

// margin is gray for if in ink mode 



Messages 



S sj^;^>6**iH:S:s^'ftMj&iS;KS'C'S'SS 



msgGestureMarginGetStyle 

Passes back the receiver's current style values. 

Takes P_GESTURE_MARGIN_STYLE, returns STATUS. 

♦define msgGestureMarginGetStyle MakeMsg (clsGestureMargin, 1) 
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tessog© typedef struct GESTURE_MARGIN_STYLE { 

Arguments U16 gestureMargin : 1, // gesture margin on/off 

wideGestureMargin : 1, // make the gesture margin wide 

// (not implemented) 



maskGestureMargin 

inkMode 

reserved 



1, // mask out gestureMargin 
1, // margin is gray for if in ink mode 
12; 



} GESTURE_MARGIN_STYLE, *P_GESTURE_MARGIN_STYLE; 

msgGestureMarginSetStyle 

Sets the receiver s style values. 

Takes P_GESTURE_MARGIN_STYLE, returns STATUS. 

#define msgGestureMarginSetStyle MakeMsg(clsGestureMargin, 2) 

typedef struct GESTURE_MARGIN_STYLE { 

U16 gestureMargin : 1, // gesture margin on/off 

wideGestureMargin : 1, // make the gesture margin wide 

// (not implemented) 



maskGestureMargin 

inkMode 

reserved 



1, // mask out gestureMargin 
1, // margin is gray for if in ink mode 
12; 



} GESTURE_MARGIN_STYLE, *P_GESTURE_MARGIN STYLE; 

msgGestureMarginSetlnkMode 

Sets margin to be either ink or gesture mode. 

Takes BOOLEAN, returns STATUS. 

♦define msgGestureMarginSetlnkMode MakeMsg(clsGestureMargin, 3) 



HASH.H 



This package implements an "Open Addressing, Linear Probe" hash table. 
The functions described in this file are contained in SYSUTIL.LIB. 

Introduction 

This package implements hash tables. Hash tables offer relatively fast key-based random access to data at 
the expense of some memory. The performance improvement over linear searching is substantial. 

The defaults supplied by this package are probably fine for most data. However, hash table performance 
depends on both a good hash function and proper size parameters. If your data's keys are unevenly 
distributed then consider writing your own hash fiinction. Try to get the hash table's initial size close to 
the number of expected entries divided by the fill percentage. You can vary the fill percentage to meet 
your tradeoffs between space and time. 

Creating a Hash Table 

To create a hash table: 

♦ Allocate space for the hash table (either on the stack or in a heap block) 

♦ Call HashlnitDefaultsQ 

♦ Optionally customize the HASH_INFO structure 

♦ Call HashlnitQ 



Examples 



Here's some sample code based on a 32 bit key. (The package has built-in Hash and Compare fiinctions 
for 32 bit keys; see section "Hash and Compare Functions.") 

// Client data structure. (The structure must contain a key field, 

// though it need not be named key and it need not be the first field.) 

typedef struct { 

U32 data; 

U32 key; 
} YOUR DATA, *P YOUR DATA; 



{ 



P_HASH_INFO pHashlnfo; 

P_YOUR_DATA pMD; 

U32 key; 

// Create table. 

OSHeapBlockAlloc(osProcessHeapId, sizeof (*pHashInfo) , &pHashInfo) ; 

HashlnitDefaults (pHashlnfo) ; 

// Optionally customize between calls to HashlnitDefaults () and 

// Hashlnit(). For instance, if you have 16 bit keys, you 

// might do the following: 

// pHashInfo->pHashFunction = HashFunctionl6; 

// pHashInfo->pHashCompare = HashComparel6; 

Hashlnit (pHashlnfo, of f setof (YOUR_DATA, key) ) ; 



222 PENPOINT API REFERENCE 

Part 9 / Utility Classes 



// Add entry to hash table 

OSHeapBlockAlloc(osProcessHeapId, SizeOf (YOUR_DATA) , &pMD) ; 
pMD->key =25; 
pMD->data = someData; 
HashAddEntry(pHashInfo, pMD) ; 

// Find entry in hash table. Returns stsNoMatch if not found. 

key = 25; 

HashFindData(pHashInfo, &key, &pMD) ; 

DebugfC'Data for key %d is %d", key, pMD->data) ; 

// Delete entry in hash table without freeing client data. 

// Returns stsNoMatch if not found. 

key = 25; 

HashDeleteEntry (pHashlnfo, &key, &pMD, false); 

OSHeapBlockFree (pMD) ; 

// Delete entry in hash table and free the client data. 

// Returns stsNoMatch if not found. 

key - 25; 

HashDeleteEntry (pHashlnfo, &key, &pMD, true); 

// Free hash table, and call OSHeapBlockFree ( ) on all client data. 
HashFree (pHashlnfo, true) ; 

OSHeapBlockFree (pHashlnfo) ; 



Enumerating Hash Table Entries 

All of the entries in a hash table can be enumerated by examining the entries field of the HASHJNFO 
structure. Empty entries are null. Note that there are numEntries slots, numPilled of which are 
non-null. 

P_HASH_INFO pHashlnfo; 
P_HASH_ENTRY pEntries; 

pEntries = pHashInfo->entries; 

for (i = 0; i < pHashInfo->nuinEntries; i++) { 

if (pEntries [i] .pData) { 

// Do something with entry 

} 
} 

Hash and Compare Functions 

The package includes good Hash and Compare functions for the following types of keys: 

♦ 16 bit numbers 

♦ 32 bit numbers 

♦ 64 bit numbers 

♦ null-terminated strings 

Clients with other key types need to provide their own Hash and Compare functions. Sophisticated 
clients may want to provide their own Hash and Compare functions even if they have keys with one of 
the above types. 
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Replacement Hash and Compare functions should look like the following: 



typedef struct { 

U8 major; 

U16 minor; 
} MY_KEY, * P_My_KEY; 

typedef struct { 

MY_KEY key; 

P_UNKNOWN pData; 
} MY_DATA, * P_MY_DATA; 

U32 EXPORTED 
MyKeyHashFunction ( 

P_HASH_KEY pKey) 
{ 

P_MY_KEY pMyKey = (P_MY_KEY)pKey; 

U32 hash; 

hash = pMyKey->major * 9551; 

hash += pMyKey->minor * 113; 

return hash; 
} 
BOOLEAN EXPORTED MyKeyHashCompare ( 



// 9551 is prime 
// 113 is prime 



P_HASH_KEY 
P HASH KEY 



pKeyl, 
pKey2) 



P_MY_KEY pMyKeyl = (P_MY_KEY)pKeyl; 
P_MY_KEY pMyKey2 = (P_MY_KEY)pKey2; 
return ( (pMyKeyl->major == pMyKey2->major) AND 
(pMyKeyl->minor == pMyKey2->minor) ) ; 



Space / Time Tradeoff 

The following table show the space / time tradeoff for a variety of percentFull values, normalized to 
80%. This table is a gross simplification. Among other things, it assumes well distributed keys. 



full per- 


relative 


relative 


centage 


speed 
2.8 


memory use 


10 


8.0 


20 


2.7 


4.0 


30 


2.5 


2.7 


40 


2.3 


2.0 


50 


2.0 


1.6 


60 


1.7 


1.3 


70 


1.4 


1.2 


80 


1.0 


1.0 


90 


.6 


.9 


95 


.3 


.8 



tifndef HASH_INCLUDED 
♦define HASH_INCLUDED 

tinclude <string.h> 
#ifndef GO_INCLUDED 
#include <go.h> 
#endif 

#ifndef OSTYPES_INCLUDED 
tinclude <ostypes.h> 
#endif 

tifndef OSHEAP_INCLUDED 
tinclude <osheap.h> 
tendif 

tinclude <stddef .h> 
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Common #defines and typedefs 

Default values 



♦define minHashTablelnitialSize 15 
fdefine ininHashTableExpandSize 16 
tdefine hashTableMaxFillPct 80 



// minimum initial size 

// minimum expand increment 

// expand when the table gets this 

// percentage full. 



Fyncfion Frotofyp* 



*rofotyp« 



Key and Data Pointer Types 

typedef void * P_HASH_KEY; 
typedef void * P_HASH_DATA; 

Type for Hash function 

typedef U32 FunctionPtr {HASH_FUNCTION) ( 

P_HASH_KEY pKey 
); 

Type for Compare function. Function should return true if pKeyl and pKey2 point to keys with 
identical values. 

typedef BOOLEAN FunctionPtr (HASH_COMPARE) ( 

P_HASH_KEY pKeyl, 

P_HASH_KEY pKey2 

); 

A hash table entry. 



typedef struct HASH_ENTRY { 

P_HASH_DATA pData; // Points to user data 

} HASH ENTRY, * P HASH ENTRY, ** PP HASH ENTRY; 



The hash table itself Space for the table is allocated by the client. Space for the entries is allocated by 
hash table functions and is freed via a call to HashFree(). 

The debugging version of the hash table gathers statistics. 



typedef struct HASH_INFO { 

U32 numEntries; 



U32 



U32 
U32 



numFilled; 



expandNumber ; 
percentFull; 



U16 keyOffset; 

OS_HEAP_ID heap; 
P HASH ENTRY entries; 



HASH_FUNCTION pHashFunction; 
HASH_COMPARE pHashCompare; 
// Statistics maintained for DEBUG 
U32 numProbes; 

U32 numProbeMisses; 

U32 numAdds; 

U32 numDeletes; 

HASH INFO, * P HASH INFO; 



// number of entries allocated. 
// Should be prime! 
// number of entries in use. Not 
// too small or table will expand too 
// often. Should be even. 
// number of entries to expand by 
// max percentage full at expand time. 
// Performance falls off rapidly if 
// table allowed to get much fuller 
// than 80%. 

// offset of key in P_HASH_DATA 
// heap to expand into 
// points to hash table array. 
// Array can be indexed sequentially 
// to find all the entries in the 
// table. Empty slots are null. 
// Hash function 
// Compare function 
version 
// Counts number of hash probes 
// Counts number of probe retries 
// Counts number of adds 
// Counts number of deletes 
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Common #defines and typedefs 



Functions 



HashFindData 

Given a key, passes back a P_HASH_DATA. 

Returns STATUS. 

Foncficn Fmfotype STATUS EXPORTED HashFindData ( 

P_HASH_INFO pinfo, «« 

P_HASH_KEY pKey, S 

P HASH DATA * ppData) ; 3 

— — u 

Return Voiue stsNoMatch the key is not in the table. *ppData is undefined. ^ 

stsOK the key is in the table. => 

See Also HashFindTableEntry "^ 

HashFindTableEntiy 

Given a key, passes back a pointer to client data. 

Returns STATUS. 

STATUS EXPORTED HashFindTableEntry ( 
P_HASH_INFO pInfo, 
P_HASH_KEY pKey, 
PP_HASH_ENTRY ppEntry) ; 

StsNoMatch the key is not in the table. *ppEntry is undefined. 

StsOK the key is in the table. 

HashFindData 



HashAddEntry 

Adds an entry to a hash table. 

Returns STATUS. 

fumtmn Prototype STATUS EXPORTED HashAddEntry ( 
P_HASH_INFO pInfo, 

P_HASH_DATA pData) ; 

Commsnu The hash table expands if adding this entry causes the table to exceed the expand threshold. 

io. i;. '^^ '^ stsFailed the key is already in the table 



HashDeleteEntry 

Deletes entry firom hash table. 

Returns STATUS. 

STATUS EXPORTED HashDeleteEntry ( 
P_HASH_INFO pInfo, 

P_HASH_KEY pKey, 

P_HASH_DATA * ppData, 
BOOLEAN freeClientData) ; 

If freeClientData is true then the client data is deallocated using ppData is undefined. Otherwise 
*ppData contains the pointer to client data. 

Freeing entries does not cause the table to shrink. 

StsNoMatch the key is not in the table. 
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HashlnitDefaults 

Initializes hash table parameters. 

Returns STATUS. 

Funetiori Prototype STATUS EXPORTED HashlnitDefaults ( 
P_HASH_INFO pinfo) ; 

CoR«Ti©«ts Warning: HashlnitDefaults () MUST be called before Hashlnit. See the section "Examples." 

Default values: 

memset (pInfo, 0, sizeof {HASH_INFO) ) ; 

pInfo->numEntries = 31; 

pInfo->expandNumber = 24; 

pInfo->heap = osProcessHeapId; 

pInfo->pHashFunction = HashFunction32; // Default 32 bit key 

pInfo->pHashCompare = HashCompare32 ; // Default 32 bit key 

pInfo->percentFull = 80; 

Hashlnit 

Causes the hash table to allocate internal tables. 

Returns STATUS. 

Fwnctiori Prototype STATUS EXPORTED Hashlnit ( 
P_HASH_INFO pInfo, 

U32 keyOffset); // offset of key in client data. 

Comtiients The client must call this function after calHng HashlnitDefaults () and performing any optional 

customization. 

Example: 

HashlnitDefaults (pInfo) ; 

Hashlnit (pInfo, of f setof {YOUR_DATA, key)); 

HashFree 

Frees internal hash table memory. Optionally deallocates any remaining user data blocks. 

Returns STATUS. 

Fiinctiop Protetype STATUS EXPORTED HashFree ( 
P_HASH_INFO pInfo, 

BOOLEAN freeAllEntries) ; 

CoRime«fs If freeAllEntries is true, then the hash table calls OSHeapBlockPreeQ on each remaining piece of client 

data. 

If the client is going to call HashFree() with freeAllEntries false, the client must free all client data 
beforehand. 

Note that this function does NOT free the HASHJNFO structure. If the client allocated it before calling 
HashlnitQ then the client should free the table after calling HashFreeQ. 
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Built-in Hash and Compare Functions 



P^ Built-in Hasii and Compare Functions 

The functions in this section are useful defauh hash and compare functions for common key types. The 
64 bit, 32 bit, and 16 bit functions work equally well for signed or unsigned values. 

P^ 64 bit keys 

Funcfion Pmtotype U32 EXPORTED HashFunction64 (P_HASH_KEy pKey) ; 

BOOLEAN EXPORTED HashCompare64 (P_HASH_KEY pKeyl, P_HASH_KEY pKey2); 



^ 32 bit keys 



Function Prototype U32 EXPORTED HashFunction32 (P_HASH_KEY pKey) ; 

BOOLEAN EXPORTED HashCompare32 {P_HASH_KEY pKeyl, P_HASH_KEY pKey2); 



^ 1 6 bit keys 



Fynctbn Prototype U32 EXPORTED HashFunctionl6 (P_HASH_KEY pKey) ; 

BOOLEAN EXPORTED HashComparel6 (P_HASH_KEY pKeyl, P_HASH_KEY pKey2) ; 



String keys 



Function Prototype U32 EXPORTED HashFunctionString (P_HASH_KEY pKey) ; 

BOOLEAN EXPORTED HashCompareString (P_HASH_KEY pKeyl, P_HASH_KEY pKey2) ; 
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IMPORT.H 



This file contains the API definition for clslmport. 

clslmport inherits fi:om clsObject. 

clslmport is the abstract class defining the API for importing foreign files from external disks into 
notebook documents. 

Overvievs^ 

The import protocol is triggered when the TOC receives msgSelMoveSelection or 
msgSelCopySelection the TOC, and the source of the move/copy includes clsFileSystem as an item in 
the list returned by msgXferList, then the TOC initiates the import protocol. (See xfer.h and sel.h for 
information on PenPoint's move/copy protocol and selection management.) 

The import protocol sends msglmportQuery, as a class message, to each installed application class to 
determine the set of applications that can import the file. 

Once every installed application has been queried, clsApp will put up an import dialog box. An instance 
of the application is created on the destination and msglmport is sent. If the import succeeds, the 
importer should return stsOK. If an error occurs and the user has not been notified of the failure, the 
importer should return stsImportFaiied. If an error occurs and the user has been notified, the importer 
should return stsImportFailedUserNotified. 

Hovsf to Be an Importing Application 

Any application that wants to import must handle msglmportQuery and msglmport. 

The import protocol sends msglmportQuery as a class message. (See clsmgr.h for more general 
information about class messages.) For your app to receive a class message you must have an entry 
something like this in your application class's method table: 

MSG_INFO myAppMethods [] = { 

msglmportQuery, "MyAppImportQuery", objClassMessage, 



}; 



The 'ImportQueryHandler' method can look at the contents or the name of the imported file to 
determine if that file can be imported by the app. If the app can import the file, the 
'ImportQueryHandler' method sets the pArgs->canImport boolean to true (the default is false) and 
returns stsOK. The TOC will then add the application's name to the list of possible import destinations 
for the import dialog. 



tifndef IMPORT_INCLUDED 
tdefine IMPORT_INCLUDED 

#ifndef GO_INCLUDED 

tinclude <go.h> 

#endif 

tifndef UID_INCLUDED 

tinclude <uid.h> 

tendif 

tifndef FS_INCLUDED 
tinclude <fs.h> 
tendif 
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Common #clefines and iypedefs 



Status codes 



Importing applications should re stsImportFailedUserNotified if the importer detected an error during 
the importation and notified the user of the error. This allows the importer to give a more detailed error 
message to the user. 



#define stsImportFailed 

Idefine StsImportFailedUserNotified 

#define stsImportlnvalidFormat 



MakeStatus(clsImport, 1) 
Makes tat us (els Import, 2) 
MakeStatus( els Import, 3) 



Messages 



msglmportQuery 

Queries each app class to see if it is capable of importing the file. 

Takes P_IMPORT_QUERY, returns STATUS. Category: client responsibility. 

tdefine msglmportQuery MakeMsg(clsImport, 1) 



typedef struct { 
FILE_HANDLE 
TAG 
CHAR 
BOOLEAN 

U16 



U8 



file; 

fileType; 

f ileName [nameBuf Length] ; 

can Import; 

suitabilityRating; 



spare [ 64 ] ; 



// Open file handle to imported file. 

// File type if it exists. 

// Source file name. 

// Out: TRUE if app can import the file, 

// Default setting on entry is false. 

// Out: - lowest 

// 50 - average (default) 

// 100 - highest 

// Spare: reserved. 



} IMPORT_QUERY, *P_IMPORT_QUERY; 

This message is sent by the brow^ser to each application class. The applicatin should pass back 
pArgs->canImport set to true if it can import the file. pArgs->suitabilityRating is the relative rating of 
how suitable the application is to importing the file. This rating determines the ordering within the list 
of applications in the import dialog box displayed by PenPoint. 



msglmport 

Initiates the import. 

Takes P_IMPORT_DOC, returns STATUS. Category: client responsibility. 

tdefine msglmport MakeMsg(clsImport,2) 



typedef struct { 

FILE_HANDLE file; 

TAG 

U8 

U32 

DIR HANDLE 



fileType; 

f ileName [nameBuf Length] ; 

sequence; 

destHandle; 



// Open file handle to file. 

// File type if exists. 

// Source file name. 

// Sequence number for dest. 

// Dir handle to dest section. 



} IMPORT DOC, *P IMPORT DOC; 



This message is sent by clsApp to a newly created instance of the destination application. The 
application should import the data from the file and return stsOK. If this message returns an error status 
the newly created app instance will be deleted. 
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Miscellaneous 



Miscellaneous 

Help tags 

These are help tags on various pieces of the standard export dialog box. 

♦define hlpImportSheet MakeTag(clsImport, 50) 

♦define hip Import Name MakeTag(clsImport, 51) 

♦define hlpImportNewName MakeTaglclsImport, 52) |2 

♦define hlpImportChoice MakeTag(clsImport, 53) S 
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LIST.H 



This file contains the API definition for clsList. 
clsList inherits from clsObject. 

Lists are a simple ordered collections of items. 

#ifndef LIST_INCLUDED 
tdefine LIST_INCLUDED 

#ifndef CLSMGR_INCLUDED 
♦include <clsmgr.h> 
tendif 



Common #defines and typedefs 



typedef OBJECT LIST, *P_LIST; 

typedef P_UNKNOWN LIST_ITEM, *P_LIST_ITEM; 

LIST_ENTRY is used in many messages. In general, the fields are treated as follows: 

♦ position. An item's location. Locations are zero-based. The first item is and the last item is number 
of items - 1 . When used as an In parameter, position specifies the position of the item to operate on. 
For adding operations, maxUl6 means beyond the last item. For other operations, niaxU16 means 
the last item in the list. Values beyond the size of the list but less than maxUl6 are not 
recommended. When used as an Out parameter, position contains the actual position of the item. 
maxU16 is never passed back even if passed in. 

♦ item. When used as an In parameter, item identifies the item to operate on. If the same item added 
to the list more than once, then all operations work only the first appearance of the item. When 
used as an Out parameter, item contains the item operated on. 

typedef struct LIST_ENTRY { 

U16 position; 

LIST_ITEM item; 
} LIST_ENTRY, *P_LIST_ENTRY; 

typedef struct LIST_NOTIFY { 

MESSAGE msg; // In: 

P_ARGS pArgs; // In: 

SIZEOF lenSend; // In: 

} LIST NOTIFY, * P LIST NOTIFY; 



message to send/post 
pArgs for message 
length of pArgs 



Status Codes 



tdefine stsListFull 
♦define stsListEmpty 



MakeStatus (clsList, 1) 
MakeStatus (clsList, 2) 
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Messages Defined by Other Classes 



msgNew 

Creates a new empty list. 

Takes P_LIST_NEW, returns STATUS. Category: class message. 

Arguments typedef struct LIST_STYLE { 

U16 reserved: 16; 

} LIST_STYLE, * P_LIST_STYLE; 

List filing behavior. 

typedef enum LIST_FILE_MODE { 

listFileltemsAsData, // File list items as U32 data. 

listFileltemsAsObjects, // Treat list items as objects. Save 

// them with msgResPutObject and restore 
// them with msgResGetObject. 

listDoNotFileltems // Don't file list items. 

} LIST_FILE_MODE, *P_LIST_FILE_MODE; 
typedef struct LIST_NEW_ONLY { 

LIST_STYLE style; 

LIST_FILE_MODE fileMode; 

U32 reserved[4]; // Reserved 

} LIST_NEW_ONLY, *P_LIST_NEW_ONLY; 

tdefine listNewFields \ 
objectNewFields \ 
LIST_NEW_ONLY list; 

typedef struct LIST_NEW { 

listNewFields 
} LIST_NEW, *P_LIST_NEW; 

If the heap specified in pArgs->object.heap is null, the process heap is used. 

msgNewDefaults 

Initializes the LIST_NEW structure to default values. 

Takes P_LIST_NEW, returns STATUS. Category: class message. 

typedef struct LIST_NEW { 

listNewFields 
} LIST_NEW, *P_LIST_NEW; 

Zeroes out pNew->list and sets: 

pArgs->list. fileMode = listFileltemsAsObjects 

msgSave 

Defined in clsmgr.h 

Takes P_OBJ_SAVE, returns STATUS. 

In response to this message, the list saves itself Then, based on the list's fiileMode, it may save the item 
information. See the commentary with the type LIST_FILE_MODE for more information. 



imments 
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List Manipulation Messages 



msgRestore 

Defined in clsmgr.h 

Takes P_OBJ_RESTORE, returns STATUS. 

Comments In response to this message, the list restores itself. Then, based on the Hst's fileMode, it may restore the 

items information. See the commentary with the type LIST_FILE_MODE for more information. 

^List Manipulation Messages | 



msgListFree 

Frees a list according to mode. 

Takes P_LIST_FREE, returns STATUS. 

tdefine msgListFree MakeMsg(clsList, 1) 

Arguments typedef enum LIST_FREE_MODE { 

listFreeltemsAsData, // Ignore the item's value. Simply destroy 

// the list itself. Equivalent to sending 
// msgDestroy to the list. 
listFreeltemsAsObjects, // Treat items as objects. Send each item 

// msgDestroy Nil (key) before destroying 
// the list itself. Any errors are ignored. 
listDoNotFreeltems // Obsolete. Do not use. 

} LIST_FREE_MODE, *P_LIST_FREE_MODE; 

typedef struct LIST_FREE { 

OBJ_KEy key; // Key for freeing the list object. 

LI ST_FREE_MODE mode ; 
} LIST_FREE, *P_LIST_FREE; 

Cmnmenfs In response to this message, the list destroys itself AND all of its items. 

Use msgDestroy to destroy the list without affecting the list's items. For both messages, observers are 
sent msgListNotifyEmpty. 



»0mmeiifs 



msgListAddltem 

Adds an item to the end of a list. 

Takes LIST_ITEM, returns STATUS. 

#define msgListAddltem MakeMsg(clsList, 2) 

Observers are sent msgListNotifyAddition. 



msgListAddltemAt 

Adds an item to a list at pArgs->position. 

Takes P_LIST_ENTRY, returns STATUS. 

#define msgListAddltemAt MakeMsg(clsList, 10) 

Message typedef Struct LIST_ENTRY { 

Argymeote U16 position; 

LIST_ITEM item; 
} LIST_ENTRY, *P_LIST_ENTRY; 

Comments If the list is empty, pArgs->position is treated as if it were 0. If pArgs->position is maxU16, the item is 

inserted at the end of the list. 
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If necessary, list items move to make room for tlie new item. 
Observers are sent msgListNotifyAddition. 
ieturrs ¥alye stsOK item added. pArgs->position contains tlie actual position of the new item. 



msgLlstRemoveltem 

The list searches for pArgs in the list and removes the item if found. 

Takes LISTJTEM, returns STATUS. 

#define msgListRemoveltem MakeMsg(clsList, 11) 

Comments If the argument is in the list more than once, only the first instance of it is removed. 

Observers are sent msgListNotifyDeletion. 
ietyrn Value stsListEmpty the list was empty 

stsNoMatch item was not found 



msgListRemoveltemAt 

Removes the item in the list at pArgs->position. 

Takes P_LIST_ENTRY, returns STATUS. 

tdefine msgListRemoveltemAt MakeMsg(clsList, 3) 

Message typedef struct LIST_ENTRY { 

fergprnents U16 position; 

LIST_ITEM item; 
} LIST_ENTRY, *P_LIST_ENTRY; 

omments Observers are sent msgListNotifyDeletion. 

stum Value stsListEmpty the list was empty 

StsOK item removed. pArgs->position contains the position of the removed item. 



msgListReplaceltem 

Replaces the item in the list at pArgs->position. 

Takes P_LIST_ENTRY, returns STATUS. 

#define msgListReplaceltem MakeMsg(clsList, 4) 

Messoge typedef struct LIST_ENTRY { 

Arguments U16 position; 

LIST_ITEM item; 
} LIST_ENTRY, *P_LIST_ENTRY; 

Comnients If pArgs->position is maxU16, the last item in the list is replaced. 

Observers are sent msgListNotifyReplacement. 

ietyrn Value StsListEmpty the list was empty 

StsOK item was replaced. pArgs->item contains the old item and pArgs->position contains its old 
position. 
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msgListGetltem 

Gets the item in the Hst at pArgs->position. 

Takes P_LIST_ENTRY, returns STATUS. 

tdefine msgListGetltem MakeMsg(clsList, 5) 

«essoge typedef struct LIST_ENTRY { 

Arguments U16 position; 

LIST_ITEM item; J2 

} LIST_ENTRY, *P_LIST_ENTRY; m 

:omments If pArgs->position is maxUl 6, the last item in the list is returned. " 

leturo Value stsListEmpty the list was empty. 



stsOK item found. pArgs->position contains the position of the item. 

msgListFindltem 

Searches for pArgs->item in the list. 

Takes P_LIST_ENTRY, returns STATUS. 

tdefine msgListFindltem MakeMsg(clsList, 6) 



fessogsi typedef struct LIST_ENTRY { 

irgyments U16 position; 

LIST_ITEM item; 
} LIST ENTRY, *P LIST ENTRY; 



stsNoMatch item was not found. 

StsOK item was found. pArgs->position contains the position of the item. 

msgListNumltems 

Passes back the number of items in a list. 

Takes P_U16, returns STATUS. 

tdefine msgListNumltems MakeMsg(clsList, 7) 

msgListRemoveltems 

Removes all of the items in a list. 

Takes no arguments, returns STATUS. 

tdefine msgListRemoveltems MakeMsg(clsList, 8) 

The list's items are not affected in any way. 

Observers are sent msgListNotifyEmpty. 



msgListEnumltems 

Enumerates the items in a list. 

Takes P_LIST_ENUM, returns STATUS. 

tdefine msgListEnumltems MakeMsg{clsList, 9) 



Arguments typedef struct LIST_ENUM { 

U16 max; 

U16 count; 

P_LIST_ITEM pitems; 
P_UNKNOWN pNext; 
} LIST ENUM, * P LIST ENUM; 
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Comments This copies successive items from die list into an array. There are two approaches a cHent can use: 

1 . Let the Hst do all the work in one call. The list allocates an array of items which is passed back in 
pArgs->pItems. You must free this array when you are done with a call to OSHeapBlockFree. 
LIST_ENUM Should be filled in as follows: 

max On input, should be 0. On output, will be the the number of items in the allocated block. 

count On input, should be maxUl6. On output will be the same as max. 

pitems On input, should be null. On output, will be the pointer to the allocated block. 

pNext On input, should be null. 

2. Go through the items, a chunk at a time. Repeatedly call msgListEnumltems with the same 
LIST_ENUM structure and processes successive groups of items. The call that returns stsEndOfData 
indicates that the enumeration is finished (there are no more items to process). LIST_ENUM is used as 
follows: 

max On input and output, the number of items your block can hold 

count On input, the same as max. On output, will be the number of items returned in block. (This 
will be less than max the last time through.) 

pitems On input, a pointer to a block that can hold at least max items. 

pNext On input for first call, should be null. Do not modify thereafi:er. 

Return Voi»e stsEndOfData There are no more items to enumerate (list may be empty). When stsEndOfData is 

returned, pArgs->count is zero. If you passed in pitems as null and max as 0, the block may not 
have been allocated. Check pitems for nil and free it if it isn't. 



msgListGetHeap 

Passes back the heap used by the list. 

Takes P_OS_HEAP_ID, returns STATUS. 

#define msgListGetHeap MakeMsg(clsList, 12) 

Forwarding Messages 

clsList responds to these messages by sending the specified message to each item in the list in turn. 
clsList ignores the values returned by sending this message and always returns stsOK. 



msgListCall 

Sends a message to each object in the list using ObjectCall. 

Takes P_LIST_NOTIFY, returns STATUS. 

tdefine msgListCall MakeMsg (clsList, 13) 

tessage typedef struct LIST_NOTIFY { 

trgumenfs MESSAGE msg; // In: message to send/post 

P_ARGS pArgs; // In: pArgs for message 

SIZEOF lenSend; // In: length of pArgs 

} LIST NOTIFY, * P LIST NOTIFY; 



LIST.H 239 

Observer Notifications 



msgListSend 

Sends a message to each object in the hst using ObjectSend. 

Takes P_LIST_NOTIFY, returns STATUS. 

tdefine msgListSend MakeMsg(clsList, 14) 

tessoge typedef struct LIST_NOTIFY { 

l,rgumente MESSAGE msg; // In: message to send/post 

P_ARGS pArgs; // In: pArgs for message 



M 



SIZEOF lenSend; // In: length of pArgs Jg 

} LIST NOTIFY, * P LIST NOTIFY; u 



msgListPost 

Sends a message to each object in the list using ObjectPost. 

Takes P_LIST_NOTIFY, returns STATUS. 

#define msgListPost MakeMsg{clsList, 15) 

message typedef struct LIST_NOTIFY { 

ftrgymenfs MESSAGE msg; // In: message to send/post 

P_ARGS pArgs; // In: pArgs for message 

SIZEOF lenSend; // In: length of pArgs 

} LIST_NOTIFY, * P_LIST_NOTIFY; 

F Observer Notifications 

A list uses msgPostObservers to deliver all of its notification messages. (See clsmgr.h for more 
information.) 

msgListNotifyAddition 

Notifies observers that an item has been added to the list. 
Takes P_LIST_NOTIFY_ADDITION, returns STATUS. 

typedef struct LIST_NOTIFY_ADDITION { 

LIST list; // the affected list 

LIST_ITEM list Item; // the affected list item 

U16 count; // new number of entries 

U8 reserved [40 ] ; 

} LIST_NOTIFY_ADDITION, * P_LIST_NOTIFY_ADDITION; 

tdefine msgListNotifyAddition MakeMsg ( clsList, 16 ) 



msgListNotifyDeletion 

Notifies observers that an item has been deleted from the list. 

Takes P_LIST_NOTIFY_DELETION, returns STATUS. 

Argyments typedef struct LIST_NOTIFY_DELETION { 

LIST list; // the affected list 

LIST_ITEM listltem/ // the affected list item 

U16 count; // new number of entries 

U8 reserved [40] ; 

} LIST_NOTIFY_DELETION, * P_LIST_NOTIFY_DELETION; 

fdefine msgListNotifyDeletion MakeMsg ( clsList, 17 ) 
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msgListNotifyReplacement 

Notifies observers that an item in the list has been replaced. 

Takes P_LIST_NOTIFY_REPLACEMENT, returns STATUS. 

typedef struct LIST_NOTIFY_REPLACEMENT { 

// the affected list 
// the new list item 
// the replaced list item 
// index of replace item 

} LIST_NOTIFY_REPLACEMENT, * P_LIST_NOTIFY_REPLACEMENT; 

#define msgListNotifyReplacement MakeMsg ( clsList, 18 ) 



LIST 


list; 


LIST ITEM 


newListltem; 


LIST ITEM 


oldListltem; 


U16 


index; 


U8 


reserved [40] 



msgListNotifyEmpty 

Notifies observers that a list is now empty. 
Takes P_LIST_NOTIFY_EMPTY, returns STATUS. 



Arguments typedef Struct LIST_NOTIFY_EMPTY { 

LIST list; // the affected list 

US reserved [40] ; 

} LIST_NOTIFY_EMPTY, * P_LIST_NOTIFY_EMPTY; 

#define msgListNotifyEmpty MakeMsg ( clsList, 19 ) 






NOTEPAPR.H 



This file contains the API definition for clsNotePaper, clsNotePaper inherits from clsView. 

NotePaper is the view class for PenPoint's ink-management or note-taking building block. Most of the 
code for the MiniNote application actually resides in the building block. Other classes of the building 
block are clsNPData (the data class), clsNPItem (the generic data item), clsNPScribbleltem (the ink 
data item), clsNPTextltem (the text data item), and clsGestureMargin (the subclass of clsScroUWin 
that implements MiniNote s gesture margin). 

NotePaper provides standard PenPoint functionality including embedding, undo, move/copy, import, 
export, option sheets, and marks. (Supporting marks means that search and replace, spell, proof, and 
reference buttons are all supported.) 

NotePaper displays (and alters) the contents of an NPData object. For PenPoint 1.0, NotePaper keeps 
all of the items in its data object in a coordinate system with (0,0) its upper-left corner. As a result, all 
the items in the data object have a negative y coordinate. This means that as the NotePaper window 
grows in width and height, its contents remain relative to the top-left corner of the page. 

A sample applications (called npapp or "NotePaper App") demonstrating the use of the ink building 
block is included in the SDK. The ink building block is distributed as part of the SDK as a distributed 
DLL. The DLL and all resources used by the ink building block are included in the SDK in the 
DLL\NOTEPAPR directory. The resources in that directory include: 

notepaper.res: contains all resources used by NotePaper 

paper. res: contains the 8 bitmaps representing paper styles 

pen. res: contains the 4 bitmaps representing pen styles 

St rings. re: contains the source for quick help, error text, 

and undo strings 

tifndef NOTEPAPR_INCLUDED 
#define NOTEPAPR_INCLUDED 

tifndef VIEW_INCLUDED 

tinclude <view.h> 

tendif 

tifndef SYSFONT_INCLUDED 

#include <sysfont.h> 

#endif 

#ifndef ITOGGLE_INCLUDED 

♦include <itoggle.h> 

tendif 



Types and Constants 



#define clsNotePaper 



MakeGlobalWKN (2567 , 1) 



tdefine stsNotePaperNoHit 
tdefine stsNotePaperTreatAsInk 

Enuml6{NP_PAPER_STYLE) { 

npPaperRuled = 0, 

npPaperRuledLeftMargin = 1, 

npPaperRuledCenterMargin = 2, 

npPaperRuledLegalMargin = 7, 

npPaperBlank = 3, 

npPaperLeftMargin = 4, 

npPaperCenterMargin = 6, 

npPaperGrid = 5, 



MakeWa r n i ng ( c 1 sNot eP ape r , ) 
MakeWarning (clsNotePaper, 1) 



bEditMode 
bAutoGrow 
bWidthOpts 
bHideTopRule 


1/ 
1, 

1, 


bVirtualHeight 


1, 
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typedef struct NOTE_NP_PAPER_STYLE { 

U16 bEditMode : 1, // writing/ink vs. gesture/edit mode 

// auto grow height as user enters data? 
// include page widths in option sheet 
// don't paint the top ruling line for 
// the npPaperRuledxxx paper style 
// if set, NotePaper grows itself into 
//a long thin window and responds to 
// scroll win messages 
reserved : 11; // always set to 
U16 reservedl; 
} NOTE_PAPER_STYLE, *P_NOTE_PAPER_^STYLE; 

typedef struct NOTE_PAPER_METRICS { 
NOTE_PAPER_STYLE Style; 

SYSDC_FONT_SPEC paperFont; // defines the font for the paper 
NP_PAPER_STYLE paperStyle; // one of the NP_PAPER_STYLE values 
C00RD16 lineSpacing; // (in points) determines font size and 

// vertical spacing 
U8 penStyle; // use the NPPenStyleO macro 

} NOTE_PAPER_METRICS, * P_NOTE_PAPER_METRICS; 

NOTE: in NPPenStyle, color is one of: bsInkBlack, bsInkGrayXX, or bsInkWhite 
NOTE: in NPPenStyle, weight is one of: 1 = bold, = normal 

♦define NPPenStyle (color, weight) ((color & 0x7) | ((weight & 0x1) « 3)) 
#define NPPenColor (style) (style & 0x7) 

tdefine NPPenWeight (style) ((style & 0x8) » 3) 

The following definitions are included for convenience only. 

#define npPenFineBlack NPPenStyle (bsInkBlack, 0) 

♦define npPenFineGray NPPenStyle (bsInkGraySO, 0) 

♦define npPenBoldBlack NPPenStyle (bsInkBlack, 1) 

♦define npPenBoldGray NPPenStyle (bsInkGraySO, 1) 

Messages 

Next up: none; Recycle: 11-51 53 58-101 103 106 120-127 
msgNewDefaults 

Initialize pArgs. 

Takes P_NOTE_PAPER_NEW, returns STATUS. 



typedef struct { 










NOTE_PAPER_STYLE 


style; 


// as 


in 


NOTE_PAPER_METRICS 


NP_PAPER_STYLE 


paperStyle; 


// as 


in 


NOTE PAPER METRICS 


SYSDC FONT SPEC 


paperFont; 


// as 


in 


NOTE PAPER METRICS 


C00RD16 


lineSpacing; 


// as 


in 


NOTE PAPER METRICS 


US 


penStyle; 


// as 


in 


NOTE PAPER METRICS 


S32 


spares [6]; 








} NOTE PAPER NEW ONLY, 


*P NOTE PAPER 


NEW ONLY, 







♦define notePaperNewFields \ 
viewNewFields \ 
NOTE_PAPER_NEW_ONLY notePaper; 

typedef struct ( 

notePaperNewFields 
} NOTE PAPER NEW, *P NOTE PAPER NEW; 
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Comments Zeroes out pArgs->notePaper and sets: 



pArgs->notePaper. style. bEditMode = false; 

pArgs->notePaper.style.bAutoGrow = false; 

pArgs->notePaper. style. bWidthOpts = false; 

pArgs->notePaper. style. bHideTopRule = false; 

pArgs->notePaper. style. bVirtualHeight = false; 

pArgs->notePaper.paperStyle = npPaperRuled; 

pArgs->notePaper.paperFont = current user font preference 

pArgs->notePaper.penStyle = NPPenStyle(bsInkBlack, 1); ^ 

pArgs->notePaper.lineSpacing = 24; // 24 point K 

pArgs->view.createDataObject = true; < 

Various gWin and win flags are set and should only be modified by the fearless! 



u 



pArgs->gWin. style. gestureEnable = true; 3 

pArgs->gWin . style .gestureForward= true; 

pArgs->win . flags . input &= ~input InkThrough; 

pArgs->win. flags. input |= input Ink; 

pArgs->win. flags. style |= wsSendGeometry; 

pArgs->win. flags. style |= wsGrowBottom; 

pArgs->win . flags . style |= wsGrowRight; 

pArgs->win . flags . style | = wsCaptureGeometry ; 



msgNotePaperGetMetrics 

Passes back receiver's metrics. 

Takes P_NOTE_PAPER_METRICS, returns STATUS. 

tdefine msgNotePaperGetMetrics MakeMsg(clsNotePaper, 101) 

Message typedef struct NOTE_PAPER_METRICS { 

Argymeiifs NOTE_PAPER_STYLE style; 

SYSDC_FONT_SPEC paperFont; // defines the font for the paper 

NP_PAPER_STYLE paperStyle; // one of the NP_PAPER_STYLE values 

C00RD16 lineSpacing; // (in points) determines font size and 

// vertical spacing 
U8 penStyle; // use the NPPenStyleO macro 

} NOTE_PAPER_METRICS, * P_NOTE_PAPER_METRICS; 

msgNotePaperGetDcInfo 

Passes back the drawing contexts used by receiver. 

Takes P_NOTE_PAPER_DC_INFO, returns STATUS. 

tdefine msgNotePaperGetDcInfo MakeMsg(clsNotePaper, 4) 

kgwmeofs typedef struct { 

U32 units; // currently, msgDcUnitsTwips 
OBJECT dc; // transformed dc in "units" 
OBJECT dcPen; // transformed dc in pen units 
U32 reserved [4]; 
} NOTE_PAPER_DC_INFO, *P_NOTE_PAPER_DC_INFO; 

msgNotePaperGetSelType 

Passes back information about the types of items selected in receiver. 

Takes P_NOTE_PAPER_SEL_TYPE, returns STATUS. 

tdefine msgNotePaperGetSelType MakeMsg(clsNotePaper, 116) 
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typedef struct NOTE_PAPER_SEL_TYPE { 

BOOLEAN bScribble; // selection contains a scribble 

BOOLEAN bTranslated; // selection contains untranslatable text 

BOOLEAN bReservedl; 

BOOLEAN bReserved2; 
} NOTE PAPER SEL TYPE, * P NOTE PAPER SEL TYPE; 



msgNotePaperSetEditMode 

Sets receiver to either gesture/edit (true) or writing/ink (false) mode. 

Takes BOOLEAN, returns STATUS. 

tdefine msgNotePaperSetEditMode MakeMsg(clsNotePaper, 102) 

msgNotePaperSetPaperAndPen 

Sets paperStyle, lineSpacing, penColor, and penWeight. 

Takes P_NOTE_PAPER_METRICS, returns STATUS. 

tdefine msgNotePaperSetPaperAndPen MakeMsg(clsNotePaper, 104) 

je typedef struct NOTE_PAPER_METRICS { 

enfs NOTE_PAPER_STYLE Style; 

SYSDC_FONT_SPEC paperFont; // defines the font for the paper 

NP_PAPER_STYLE paperStyle; // one of the NP_PAPER_STYLE values 

C00RD16 lineSpacing; // (in points) determines font size and 

// vertical spacing 

U8 penStyle; // use the NPPenStyleO macro 

} NOTE_PAPER_METRICS, * P_NOTE_PAPER_METRICS; 

$nfs This message does not affect the pen style for selected items. 

msgNotePaperSetPenStyle 

Sets the pen style for selected items as well as the default for new items. 

Takes U32, returns STATUS. 

tdefine msgNotePaperSetPenStyle MakeMsg(clsNotePaper, 109) 



msgNotePaperGetPenStyle 

Gets the pen style for selected items (or the default if nothing selected). 

Takes U32, returns STATUS. 

tdefine msgNotePaperGetPenStyle MakeMsg(clsNotePaper, 112) 



msgNotePaperSetStyle 

Sets the receiver's style values. 

Takes P_NOTE_PAPER_STYLE, returns STATUS. 

♦define msgNotePaperSetStyle MakeMsg(clsNotePaper, 2) 
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Message typedef struct NOTE NP PAPER STYLE { 



irgysnertfs U16 bEditMode 

bAutoGrow 
bWidthOpts 
bHideTopRule 



1, // writing/ink vs. gesture/edit mode 

1, // auto grow height as user enters data? 

1, // include page widths in option sheet 

1, // don't paint the top ruling line for 

// the npPaperRuledxxx paper style 

bVirtualHeight : 1, //if set, NotePaper grows itself into 

//a long thin window and responds to 

// scroll win messages 

reserved : 11; // always set to 

U16 reservedl; SS 

} NOTE PAPER STYLE, *P NOTE PAPER STYLE; § 

_____ ^ 



msgNotePaperGetStyle 

Passes back the receiver's style values. 5 

Takes P_NOTE_PAPER_STYLE, returns STATUS. 

#define msgNotePaperGetStyle MakeMsg(clsNotePaper, 3) 
lessoge typedef struct NOTE NP PAPER STYLE { 



U16 bEditMode 
bAutoGrow 
bWidthOpts 
bHideTopRule 



1, // writing/ ink vs. gesture/edit mode 
1, // auto grow height as user enters data? 
1, // include page widths in option sheet 
1, // don't paint the top ruling line for 
// the npPaperRuledxxx paper style 
bVirtualHeight : 1, //if set, NotePaper grows itself into 

//a long thin window and responds to 
// scroll win messages 
reserved : 11; // always set to 
U16 reservedl; 
} NOTE_PAPER_STYLE, *P_NOTE_PAPER STYLE; 

msgNotePaperTranslate 

Translates untranslated scribbles in the selection. 

Takes P_NULL, returns STATUS. 

♦define msgNotePaperTranslate MakeMsg{clsNotePaper, 113.) 

msgNotePaperUntranslate 

Untranslates translated scribbles in the selection. 

Takes P_NULL, returns STATUS. 

#define msgNotePaperUntranslate MakeMsg(clsNotePaper, 114) 



o> 



msgNotePaperEdit 

Edits text and translates and edits scribbles in the selection. 

Takes P_NULL, returns STATUS. 

tdefine msgNotePaperEdit MakeMsg(clsNotePaper, 115) 

msgNotePaperTidy 

Tidies the selection by normalizing the spacing of items each line. 

Takes P_NULL, returns STATUS. 

#define msgNotePaperTidy MakeMsg(clsNotePaper, 105) 

The inter-item spacing is determined by sending msgNPItemGetWordSpacing to each item to be 
tidied. 
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msgNotePaperCenter 

Centers the entire selection. 

Takes P_NULL, returns STATUS, 

tdefine msgNotePaperCenter MakeMsg{clsNotePaper, 107) 

The selection is centered on the page as a whole, not line by line. 



msgNotePaperAlign 

Aligns the selection according to pArgs. 
Takes U32, returns STATUS. 

#define msgNotePaperAlign MakeMsg(clsNotePaper, 108) 

#define npAlignLeft 1 
tdefine npAlignRight 2 

Alignment takes place relative to the bounding box of the selection. 

msgNotePaperMerge 

Joins scribbles and text in the selection. 
Takes P_NULL, returns STATUS. 

tdefine msgNotePaperMerge MakeMsg(clsNotePaper, 110) 

CmnmenH Consecutive scribble items are combined into a single scribble item. Adjacent text items are combined 

into a single text item. Any subclass of clsNPItem that can respond to msgNPItemCanJoin and 
msgNPItemJoin can determine its own merging behavior. 

msgNotePaperSplit 

Splits scribbles and text. 

Takes P_NULL, returns STATUS. 

tdefine msgNotePaperSplit MakeMsg(clsNotePaper, 111) 

Comments First msgNotePaperSplitAsWords is self-sent. If stsRequestDenied is returned, then 

msgNotePaperSplitAsAtoms is self-sent. 



msgNotePaperAddMenus 

Modifies the passed in menu bar and appends standard NotePaper menus. 

Takes OBJECT, returns STATUS. 

tdefine msgNotePaperAddMenus MakeMsg(clsNotePaper, 117) 



msgNotePaperAddModeCtrl 

Adds the standard NotePaper mode icon to the passed in menu bar. 

Takes OBJECT, returns STATUS. 

tdefine msgNotePaperAddModeCtrl MakeMsg{clsNotePaper, 118) 
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msgNotePaperClear 

Deletes all items in receiver. 

Takes pNuU, returns STATUS. 

tdefine msgNotePaperClear MalceMsg(clsNotePaper, 119) 

msgNotePaperClearSel 

■u 

Deletes all selected items in receiver. «> 

>■ 



Takes pNull, returns STATUS. 

tdefine msgNotePaperClearSel MakeMsg(clsNotePaper, 11) 

msgNotePaperlnsertLine 

Inserts a blank line above the selection. 

Takes P_NULL, returns STATUS. 

tdefine msgNotePaperlnsertLine MakeMsg(clsNotePaper, 5) 

msgNotePaperSelectRect 

Selects items within rect in the receiver's data. 
Takes P_RECT32, returns STATUS. 

#define msgNotePaperSelectRect Ma]ceMsg(clsNotePaper, 1) 

¥aiye stsNotePaperNoHit Returned if nothing selected. 

msgNotePaperSelectLine 

Selects items whose baselines intersect rect in the receiver's data. 
Takes P_RECT32, returns STATUS. 

tdefine msgNotePaperSelectLine MakeMsg(clsNotePaper, 6) 

v«iye StsNotePaperNoHit Returned if nothing selected. 



msgNotePaperDeselectLine 

Deselects items whose baselines intersect rect in the receiver's data. 
Takes P_RECT32, returns STATUS. 

tdefine msgNotePaperDeselectLine MakeMsg{clsNotePaper, 7) 
ifum v«lye stsNotcPapcrNoHit Returned if nothing deselected. 



msgNotePaperDeleteLine 

Deletes items whose baselines intersect rect in the view's data. 
Takes P_RECT32, returns STATUS. 

tdefine msgNotePaperDeleteLine MakeMsg(clsNotePaper, 8) 

ietyrn ¥aiye StsNotePaperNoHit Returned if nothing deleted. 
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msgNotePaperScribble 

Handles scribble (including creating and insert object into view's data). 

Takes OBJECT, returns STATUS. 

tdefine msgNotePaperScribble MakeMsg(clsNotePaper, 9) 

The passed scribble's origin should be relative to the lower-left corner of the receiver. 

msgGWinGesture 

Self-sent to process the gesture. 

Takes P_GWIN_GESTURE, returns STATUS. 

fdefine msgGWinGesture MakeMsg(clsGWin, 2) 

Comments The Standard behavior of this gesture is defined in gwin.h. In addition, subclasses can return 

stsNotePaperTreatAsInk if they want the gesture to be treated as ink. In that case, an instance of 
clsNPScribbleltem will be created from the gesture's strokes. 

clsNotePaper's response to the various gestures is described in the MiniNote quick reference card. In 
gesture mode, gesture can be made anywhere in the window. However, any unrecognized gesture of 
more than two strokes will be treated as ink. In writing mode, most drawing is treated as ink (unless it is 
drawn over the selection). However, the following gestures are allowed even in writing mode: 

xgsScratchOut : delete items 

xgsPigtailVert : delete items 

xgs2Tap: select item (if over an item) 

xgsSTap: select line 

xgsPlus: toggle item (if over an item) 

xgsTapHold: begin area selection 

xgsCircleCrossOut: undo 

xgsDblCircle: create reference button 

xgsUpCaretDot : insert date/time 

xgsDblUpCaret : embed stationery 

xgsHorzCounterFlick: toggle mode 

xgsVertCounterFlick: toggle application borders 

ieturn Value stsNotePaperTreatAsInk The gesture should be treated as ink. 

See Also gwin.h 

msgAppSelectAll 

Selects all items in the view. 
Takes P_NULL, returns STATUS, 
app.h 

msgSelDelete 

Deletes selected items in the view. 

Takes P_NULL, returns STATUS. 

Comments Close the space that the selection occupies if an entire line or lines is selected and this message does is 

not sent within a move/copy episode. 

See Also sel.h 
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msgOptionAddCards 

Creates and adds the Pen and Paper option sheets. 

Takes P_OPTION_TAG, returns STATUS. 

This message is usually send to the NotePaper instance by the app framework if the instance holds the 
selection, is the client win of the app's main win, or is the client win of a scroll win that is the app's main 
win. However, to force NotePaper's option sheets to appear in the "Option" menu in other ^ 

circumstances, this message should be forwarded to the NotePaper instance by the application if ^ 

pArgs->tag is tagAppDocOptSheet. 

app.h.h 



msglmportQuery 

Indicates whether or not passed in file can be imported. 

Takes P_IMPORT_QUERY, returns STATUS. Category: class message. 

NotePaper will respond positively to this message if the first 5of the file are printable ASCII characters. 

import.h 



msglmport 

Imports the passed in file. 

Takes P_IMPORT_DOC, returns STATUS. 

After the file is imported, receiver's length is grown to accommodateimported text. If receiver's width is 
zero, it is grown to sixwide. 

tee Mso import.h 

msgExportGetFormats 

Passes back list of formats that can be exported. 
Takes P_EXPORT_LIST, returns STATUS. 
see Also export, h 

msgExport 

Writes an ASCII version of receiver's data to the passed in file. 
Takes P_EXPORT_DOC, returns STATUS. 
A translated text version of each scribble item is written out. 
lee Also export, h 

F Quick help and window tags 

Tags used in the UI of NotePaper's option sheets, menus, and quick help. 

Next up 37; Recycle: 2 

Tag values 100-120 are reserved for pen and paper styles. 

Tag values 200-255 are reserved for private window tags. 
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Mode icons 



Mode icons (tags from itoggle.h) The bitmaps corresponding to tlie two tags below are found in 
theSystemResFile. 



#define tagNotePaperWritelcon 
fdefine tagNotePaperEditlcon 

Quick help tag for mode icons 

fdefine tagNotePaperModelcon 



taglconToggleOff 
taglconToggleOn 



MakeTag(clsNotePaper, 1) 



Windovs^s 



Quick help tags for the main view and for the gesture margin. 



fdefine tagNotePaper 
#define tagNotePaperMargin 



MakeTag(clsNotePaper, 4) 
MakeTag(clsNotePaper, 5) 



Edit Menu 



fdefine tagNotePaperTranslate 
fdefine tagNotePaperEdit 
fdefine tagNotePaperClear 
fdefine tagNotePaperlnsertLine 



MakeTag(clsNotePaper, 6) 

MakeTag(clsNotePaper, 7) 

MakeTag(clsNotePaper, 34) 

MakeTag(clsNotePaper, 35) 



Pen Menu 



fdefine tagPenMenu 
fdefine tagPenFineBlack 
fdefine tagPenBoldBlack 
fdefine tagPenFineGray 
fdefine tagPenBoldGray 



MakeTag(clsNotePaper, 3) 

MakeTag(clsNotePaper, 110) 

MakeTag(clsNotePaper, 111) 

MakeTag(clsNotePaper, 112) 

MakeTag(clsNotePaper, 113) 



Arrange Menu 



fdefine 
fdefine 
fdefine 
fdefine 
fdefine 
fdefine 
fdefine 
fdefine 



tagArrangeMenu MakeTag 

tagNotePaperTidy MakeTag 

tagNotePaperCenter MakeTag 

tagNotePaperAlignLeft MakeTag 

tagNotePaperAlignRight MakeTag 

tagNotePaperMerge MakeTag 

tagNotePaperSplitAsWords MakeTag 

tagNotePaperSplit MakeTag 



Paper Option Card 

NOTE: For TagPaperStyle(n), tag n 
NPPaperStyleFromTag converts a ta 

fdefine tagPaperCard 

fdefine tagPaperStyleLabel 
fdefine tagPaperStyle 
fdefine TagPaperStyle (n) 
fdefine NPPaperStyleFromTag (t) 

fdefine tagLineSpacingLabel 
fdefine tagLineSpacing 
fdefine tagLineOtherRuling 
fdefine tagLineOtherValue 



(clsNotePaper, 8) 

(clsNotePaper, 9) 

(clsNotePaper, 10) 

(clsNotePaper, 11) 

(ClsNotePaper, 12) 

(clsNotePaper, 13) 

(ClsNotePaper, 14) 

(clsNotePaper, 15) 



is a value in the NP_PAPER_STYLE enumeration For 
g to a paper style. 

MakeTag (clsNotePaper, 16) 

MakeTag (clsNotePaper, 17) 

MakeTag (clsNotePaper, 18) 

MakeTag (clsNotePaper, 100 + n) 
(TagNum(t) - 100) 

MakeTag (ClsNotePaper, 19) 

MakeTag (clsNotePaper, 20) 

MakeTag (clsNotePaper, 21) 

MakeTag (clsNotePaper, 22) 
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Quick help 


and >vindow tags 


#define tagPaperWidthLabel 


MakeTag (clsNotePaper, 


23) 




#define tagPaperWidth 


MakeTag (clsNotePaper, 


24) 




#define tagPaperFitScreen 


MakeTag (clsNotePaper, 


25) 




♦define tagPaperFitPrinter 


MakeTag (clsNotePaper, 


26) 




♦define tagPaperOtherWidth 


MakeTag (clsNotePaper, 


27) 




♦define tagPaperOtherValue 


MakeTag (clsNotePaper, 


28) 




♦define tagPaperFontLabel 


MakeTag (clsNotePaper, 


29) 




♦define tagPaperFont 


MakeTag (clsNotePaper, 


30) 
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Pen Option Card 



♦define tagPenCard MakeTag (clsNotePaper, 31) 

♦define tagPenStyleLabel MakeTag (clsNotePaper, 32) 

♦define tagPenStyle MakeTag (clsNotePaper, 33) 

tagPenFineBlack (same value as in the pen menu) 
tagPenBoldBlack (same value as in the pen menu) 
tagPenFineGray (same value as in the pen menu) 
tagPenBoldGray (same value as in the pen menu) 



Insertion Pad 

♦define tagNotePaperSkip 



MakeTag (clsNotePaper, 36) 



Standard Error Resource Tags 

♦define stsNotePaperPageWidth 



MakeStatus (clsNotePaper, 2) 



Undo Resource Tags 



♦define tagNPUndoWriting 
♦define tagNPUndoDeletion 



MakeTag (clsNotePaper, 1) 
MakeTag (clsNotePaper, 2) 






NPDATA.H 



This file contains the API definition for clsN PData, 

clsNPData inherits fiom clsObject. 

NPData is the data class of PenPoint's ink-management or note-taking building block. (See notepapr.h 
for more information on the building block.) An NPData instance is a data base that manages items that 
follow the clsNPItem protocol. (See npitem.h). Its API defines messages for inserting, deleting, and 
enumerating the items it manages. 

tifndef NPDATA_INCLUDED 
tdefine NPDATA_INCLUDED 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

#endif 

#include <geo.h> 



Types and Constants 



tdefine clsNPData 



MakeGlobalWKN (2568, 1) 



Messages 



Next up: 39; Recycle: 4 5 6 7 15 20 33 34 



msgNewDefaults 

Initialize pArgs. 

Takes P_NP_DATA_NEW, returns STATUS. 

typedef struct { 

XY32 lineSpacing; 

XY32 baseline; 

BOOLEAN isSubData; // private to clsNPData 

S32 spare 1; 

S32 spare2; 
} NP_DATA_NEW_ONLY, *P_NP_DATA_NEW_ONLY ; 
tdefine npDataNewFields \ 

objectNewFields \ 

NP_DATA_NEW_ONLY npDat a ; 
typedef struct { 

npDataNewFields 
} NP_DATA_NEW, *P_NP_DATA_NEW; 

Zeroes out pArgs->npData and sets: 



pArgs->npData. lineSpacing. X = 0; 
pArgs->npData. lineSpacing. y = 360; 

pArgs->npData. baseline. X = 0; 
pArgs->npData. baseline. y = 360; 



// 360 twips = 18 points = 1/4" 
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Messages used to manipulate data 



msgNPDatalnsertltem 

Add item to the data base. 

Takes OBJECT, returns STATUS, 

♦define msgNPDatalnsertltem MakeMsg(clsNPData, 8) 

msgNPDatalnsertltemFromView 

Add item to tlie data base. 

Takes P_NP_DATA_ADDED_NP_ITEM_VIEW, returns STATUS. 

#define msgNPDatalnsertltemFromView MakeMsg(clsNPData, 38) 

Argumersfs typedef Struct { 

OBJECT item; // item that has been added 
OBJECT view; // view that added the item 
} NP_DATA_ADDED_NP_ITEM_VIEW, *P_NP_DATA_ADDED_NP_ITEM_VIEW; 

Comt«etits Observers w^ill be notified of which view^ is responsible for the addition. 

msgNPDataDeleteltem 

Delete an item from the data base. 
Takes OBJECT, returns STATUS. 

tdefine msgNPDataDeleteltem MakeMsg(clsNPData, 9) 
lents Returns stsFailed if item is not found. 

msgNPDataMoveltem 

Move an item within the data base. 

Takes P_NP_DATA_XY, returns STATUS. 

#define msgNPDataMoveltem MakeMsg(clsNPData, 10) 

Arguments typedef' Struct { 

OBJECT item; // item to be moved 
XY32 xy; // new position for item 
} NP_DATA_XY, *P_NP_DATA_XY; 

msgNPDataMoveltems 

Move all items below pArgs->y by pArgs->yDelta. 

Takes P_MOVE_ITEMS, returns STATUS. 

#define msgNPDataMoveltems MakeMsg{clsNPData, 1) 

typedef struct { 

COORD32 y; 

COORD32 yDelta; 
} MOVE ITEMS, *P MOVE ITEMS; 
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Messages used to enumerate over data 



ENUM_CALLBACK 

This template describes tlie the callback function used in item enumeration. 

Returns STATUS. 

Arguments typedef Struct { y, 

OBJECT data; //in - the data being enumerated over Si 

OBJECT item; //in - the item being enumerated ^ 

P_UNKNOWN clientData; //in - the client supplied data (or pointer) " 

} NP_DATA_ITEM, *P_NP_DATA_ITEM; ^ 

typedef STATUS FunctionPtr (P ENUM CALLBACK) (P NP DATA ITEM pitem) 

_____ -^ 



Your callback function takes a single parameter of type P_NP_DATA_ITEM. The clientData field is a copy 
of that you passed into the enumeration message using the ENUMJTEM or ENUM_RECT_ITEM 
structures. During enumeration, you can add new items or delete the "current" item begin enumerated. 
If you delete an item but want to keep using it, use must send it msgNPItemHold before deleting it and 
msgNPItemRelease when you are done using it. 

Some of the enumeration messages refer to bPaintOrder or "Reverse" order. Paint order refers to the 
top-to-bottom, left-to-right ordering of items. Non-paint or reverse order is simply the opposite 
ordering. Items are sorted first by line and then by their left edge. An item is considered to be on the line 
closest to its baseline. The lines are "line spacing" apart starting from the top of the page. If no lines are 
displayed to the user, it is possible that non-intuitive item ordering will result. 

Return an error status from the callback to terminate the enumeration. 



» 



msgNPDataEnumOverlappedltems 

Enumerates each item that overlaps the given rectangle. 

Takes P_ENUM_RECT_ITEMS, returns STATUS. 

#define msgNPDataEnumOverlappedltems MakeMsg(clsNPData, 2) 

typedef struct { 

P_ENUM_CALLBACK function; // in — callback function described above 
RECT32 hitRect; // in — enum items overlapping hitRect 
BOOLEAN bPaintOrder; // in — enum in paint order? 
P_UNKNOWN clientData; //in 

} ENUM RECT ITEMS, *P ENUM RECT ITEMS; 



msgNPDataEnuniBaselinelteins 

Enumerates each item whose baseline overlaps the given rectangle. 

Takes P_ENUM_RECT_ITEMS, returns STATUS. 

tdefine msgNPDataEnumBaselineltems MakeMsg(clsNPData, 19) 

fesssge typedef struct { 

irsyniesifs P_ENUM_CALLBACK function; // in — callback function described above 

RECT32 hitRect; // in — enum items overlapping hitRect 

BOOLEAN bPaintOrder; // in — enum in paint order? 

P_UNKNOWN ClientData; //in 

} ENUM RECT ITEMS, *P ENUM RECT ITEMS; 
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msgNPDataEnumSelectedltems 

Enumerates each item that is selected (in paint order). 

Takes P_ENUM_ITEMS, returns STATUS. 

#define msgNPDataEnumSelectedltems MakeMsg(clsNPData, 13) 

\rguments typedef Struct { 

P_ENUM_CALLBACK function; // in — callback function described above 
P_UNKNOWN clientData; //in 
} ENUM_ITEMS, *P_ENUM_ITEMS; 

msgNPDataEnumSelectedltemsReverse 

Enumerates each item that is selected (in reverse paint order). 

Takes P_ENUM_ITEMS, returns STATUS. 

fdefine msgNPDataEnumSelectedltemsReverse MakeMsg{clsNPData, 26) 

tessoge typedef struct { 

irguments P_ENUM_CALLBACK function; // in — callback function described above 

P_UNKNOWN clientData; // in 

} ENUM_ITEMS, *P_ENUM_ITEMS; 

msgNPDataEnumAllItems 

Enumerates each item (in paint order). 

Takes P_ENUM_ITEMS, returns STATUS. 

#define msgNPDataEnumAllItems MakeMsg(clsNPData, 14) 

Message typedef struct { 

irgumemts P_ENUM_CALLBACK function; // in — callback function described above 

P_UNKNOWN clientData; // in 

} ENUM_ITEMS, *P_ENUM_ITEMS; 

msgNPDataEnumAllItemsReverse 

Enumerates each item (in reverse paint order). 

Takes P_ENUM_ITEMS, returns STATUS. 

#define msgNPDataEnumAllItemsReverse MakeMsg{clsNPData, 27) 

Sesssge typedef struct { 

krgoftients P_ENUM_CALLBACK function; // in — callback function described above 

P_UNKNOWN clientData; // in 

} ENUM_ITEMS, *P_ENUM_ITEMS; 

msgNPDataSendEnumSelectedltems 

Enumerates each selected item (in paint order). 

Takes P_SEND_ENUM_ITEMS, returns STATUS. 

#define msgNPDataSendEnumSelectedltems MakeMsg(clsNPData, 22) 

Ifgoments typedef struct { 

P_ENUM_CALLBACK function; // in — callback function described above 

U8 clientData [32]; // in/out 

} SEND ENUM ITEMS, *P SEND ENUM ITEMS; 
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Messages used to access internal state 

Comments This message is the same as msgNPDataEnumSelectedltems, except that it it intended to be used in 

conjunction with ObjectSend rather than ObjectCall. It is used to enumerate the items in a data object 
that is not in the caller's process. Rather than a pointer to the client data being passed around, the client 
data is put into an array that is passed around. 

msgNPDataGetCurrentltem 

Passes back the current item in the receiver. 

M 
111 

Takes P_OBJECT, returns STATUS. ^ 

#define msgNPDataGetCurrentltem MakeMsg(clsNPData, 30) " 



msgNPDataGetNextltem 

Increments the current item to the next item and sets *pArgs to it. 

Takes P_OBJECT, returns STATUS. 

#define msgNPDataGetNextltem MakeMsg(clsNPData, 31) 

merits Set *pArgs to the current item before sending this message. If you set it to NULL, the first item will be 

returned. The next time you call this message after you reach the last item, stsEndOfData will be 
returned and *pArgs will be set to objNull. 

Messages used to access internal state 

msgNPDataltemCount 

Passes back the count of items in receiver. 

Takes P_U32, returns STATUS. 

tdefine msgNPDataltemCount MakeMsg(clsNPData, 17) 

msgNPDataSelectedCount 

Passes back the count of selected items in receiver. 

Takes P_U32, returns STATUS. 

tdefine msgNPDataSelectedCount MakeMsg (clsNPData, 18) 

msgNPDataSetBaseline 

Sets the receiver's baseline (used for alignment). 

Takes P_XY32, returns STATUS. 

#define msgNPDataSetBaseline MakeMsg (clsNPData, 24) 

msgNPDataGetBaseline 

Gets the receiver's baseline (used for alignment). 

Takes P_XY32, returns STATUS. 

tdefine msgNPDataGetBaseline MakeMsg (clsNPData, 25) 
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msgNPDataSetLineSpacing 

Sets receivers line spacing (used as the font size). 

Takes P_XY32, returns STATUS. 

#define msgNPDataSetLineSpacing MakeMsg(clsNPData, 35) 



msgNPDataGetLineSpacing 

Gets receivers line spacing (used as the font size). 

Takes P_XY32, returns STATUS. 

tdefine msgNPDataGetLineSpacing Ma]ceMsg{clsNPData, 36) 



msgNPDataGetBounds 

Passes back the bounding rectangle for all items in receiver. 

Takes P_RECT32, returns STATUS. 

#define msgNPDataGetBounds MakeMsg(clsNPData, 23) 

msgNPDataGetSelBounds 

Passes back the bounding rectangle for all selected items in receiver. 

Takes P_RECT32, returns STATUS. 

#define msgNPDataGetSelBounds MakeMsg(clsNPData, 32) 

msgNPDataGetFontSpec 

Passes back the receiver's font specification. 

Takes P_SYSDC_FONT_SPEC, returns STATUS. 

tdefine msgNPDataGetFontSpec MakeMsg(clsNPData, 28) 

msgNPDataSetFontSpec 

Sets the receiver's font specification. 

Takes P_SYSDC_FONT_SPEC, returns STATUS. 

tdefine msgNPDataSetFontSpec MakeMsg(clsNPData, 29) 



msgNPDataGetCachedDCs 

Passes back DCs with normal and bold fonts at the given line spacing. 

Takes P_NP_DATA_DC, returns STATUS. 

tdefine msgNPDataGetCachedDCs MakeMsg{clsNPData, 37) 

l«mertts typedef struct { 

OBJECT dcNormal; // normal font dc 

OBJECT dcBold; // bold font dc 

} NP_DATA_DCS, *P_NP_DATA_DCS ; 

niwenfs Used by items that want to measure text without the overhead of creating a DC. These DCs cannot be 

used for drawing!! 
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Messages sent to observers 



msgNPDataAddedltem 

Observers notified when item has been has been added or moved. 

Takes P_NP_DATA_ADDED_ITEM, returns STATUS. Category: observer notification. 

#define msgNPDataAddedltem MakeMsg(clsNPData, 11) 

Ul 

Argyments typedef Struct { m 

OBJECT data; // the data that the item has been added to 3 

OBJECT item; // item that has been added 
OBJECT view; // view that added the item 
} NPDATA ADDEDITEM, *P_NP DATA ADDED ITEM; 3 

"^ 
o< 



msgNPDataltemChanged 

Observers notified when item has been changed. 

Takes P_NP_DATA_ITEM_CHANGED, returns STATUS. Category: observer notification. 

tdefine msgNPDataltemChanged MakeMsg (clsNPData, 12) 

Arguments typedef Struct { 

OBJECT data; // the data 
OBJECT item; // item that has been changed 
OBJECT view; // view that changed the item 
RECT32 bounds; // maximum bounds affected by the change 
} NP_DATA_ITEM_CHANGED, *P_NP_DATA_ITEM_CHANGED; 

Comments Currently called when item is selected or deselected. 



msgNPDataHeightChanged 

Observers notified when receiver's height has been changed. 

Takes P_NP_DATA_ITEM_CHANGED, returns STATUS. Category: observer notification. 

tdefine msgNPDataHeightChanged MakeMsg (clsNPData, 21) 

Message typedef Struct { 

Arfymenfs OBJECT data; // the data 

OBJECT item; // item that has been changed 

OBJECT view; // view that changed the item 

RECT32 bounds; // maximum bounds affected by the change 
} NP_DATA_ITEM_CHANGED, *P_NP_DATA_ITEM_CHANGED; 

Comments Currently called by msgNPDataMoveltems. The bounds. origin.y field of pArgs contains the delta in 

the height of the data object. 

msgNPDataltemEnumDone 

Observers notified when an enumeration that deleted or moved items is complete. 

Takes NULL, returns STATUS. Category: observer notification. 

tdefine msgNPDataltemEnumDone MakeMsg (clsNPData, 16) 

Commetifs When this message is received by an observer client, all deletions have been completed and all moved 

items have been temporarily removed from the data object. Thus the client has the option of repainting 
all remaining items at this time and then painting moved items as they are reinserted. 

This message is handled by clsNotePaper and should not be handled by subclasses of clsNotePaper. 
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NPITEM.H 



This file contains the API definition for clsNPItem. 

clsNPItem inherits firom clsObject. 

NPItem is the item class for PenPoint's ink-management or note-taking building block. While instances 
of clsNPItem are never created, (subclasses like clsNPScribbleltem and clsNPTextltem are more 
interesting), NPItem defines a protocol as well as doing much of the work for basic operations. 

To add new item types to the ink building block, create a subclass of clsNPItem that implements the 
messages defined below in the section: "Messages that are usually overridden by subclasses." Once this 
new item is inserted into a clsNPData object it will show up in the clsNotePaper view that observes that 
object. The new item will then behave like the other item in terms of basic operations like move, copy, 
deletion, style changes, etc. 

fifndef NPITEM_INCLUDED 
tdefine NPITEM_INCLUDED 

tifndef GEO_INCLUDED 

tinclude <geo.h> 

#endif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef BORDER_INCLUDED 

tinclude <border.h> 

tendif 

Types and Constants 

tdefine clsNPItem MakeGlobalWKN (2569,1) 

tdefine stsNPItemNoSplit MakeWarning (clsNPItem, 0) 

The NPData object handles versioning for NPItem's and their subclasses. If the version of the object 
being restored matches the runtime version, nothing special is done. However, if there is a difference, the 
version number of the filed object is stamped as a U16 property onto the file using tagltemVersion as the 
property's tag. 

tdefine NP^ITEM_VERSION 1 

tdefine tagltemVersion MakeTag (clsNPItem, 0) 

Messages 

Next up: 44; Recycle: 3 



msgNewDefaults 

Initialize pArgs. 

Takes P_NP_ITEM_NEW, returns STATUS. 



typedef struct NP_ITEM_NEW_ONLY { 

RECT32 bounds; 

XY16 baseline; 

BOOLEAN selected; 

U32 penStyle; // (Pen styles are defined in notepapr.h.) 

S32 spare2; 
} NP ITEM NEW ONLY, *P NP ITEM NEW ONLY; 
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♦define npIteitiNewFields \ 

objectNewFields \ 

NP_ITEM_NEW_ONLY item; 

typedef struct NP_ITEM_NEW { 

npItemNewFields 
} NP_ITEM_NEW, *P_NP_ITEM_NEW; 

raents Zeroes out pArgs->npData and sets: 

pArgs->item.penStyle = penFineBlack; 



msgNPItemGetPenStyle 

Get the pen style of an item. (Pen styles are defined in notepapr.h.) 

Takes P_U32, returns STATUS. 

#define msgNPItemGetPenStyle MakeMsg(clsNPItem, 35) 



msgNPItemDelete 

Delete item from its data. 

Takes pNulI, returns STATUS. 

tdefine msgNPItemDelete MakeMsg(clsNPItem, 11) 

Deleting an item decrements its reference count and can cause the item to be destroyed. To prevent, call 
msgNPItemHold before calling msgNPItemDelete. Then call msgNPItemRelease after working with 
the item. 

msgNPItemPalntBackground 

Paints a gray background if the receiver is selected. 

Takes P_NP_ITEM_DC, returns STATUS. 

tdefine msgNPItemPalntBackground MakeMsg(clsNPItem, 41) 

loments typedef struct { 

OBJECT dc; // DC to paint into 

OBJECT dcPen; // equivalent DC in pen units 

} NP_ITEM_DC, *P_NP_ITEM_DC; 

>sR>an!s Subclasses should override this message if they want a different type of selection feedback. 



msgNPItemSelect 

Selects or deselects item. 

Takes BOOLEAN, returns STATUS. 

tdefine msgNPItemSelect MakeMsg(clsNPItein, 14) 

msgNPItemSelected 

Passes back item's selection status. 

Takes P_BOOLEAN, returns STATUS. 

tdefine msgNPItemSelected MakeMsg(clsNPItem, 15) 
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msgNPItemMove 

Moves item to the indicated position. 
Takes P_XY32, returns STATUS. 

♦define msgNPItemMove MakeMsg(clsNPItem, 5) 



msgNPItemDelta 

Moves item by the indicated amount 

Takes P_XY32, returns STATUS. >. 

#define msgNPItemDelta MakeMsg(clsNPItem, 6) 

3 
•v. 



U 



msgNPItemGetViewRect 

Passes back receivers bounding rectangle. 
Takes P_RECT32, returns STATUS. 

tdefine msgNPItemGetViewRect MakeMsg(clsNPItem, 19) 

msgNPItemHitRect 

Returns stsOK if receiver's bounds overlaps pArgs. 

Takes P_RECT32, returns STATUS. 

tdefine msgNPItemHitRect MakeMsg(clsNPItem, 9) 



msgNPItemGetMetrics 

Gets the item's metrics. 

Takes P_NP_ITEM_METRICS, returns STATUS. 

#define msgNPItemGetMetrics MakeMsg(clsNPItem, 20) 

Arguments typedef struct NP_ITEM_METRICS { 

//is item selected? 

// is item marked (in the clsMark sense)? 

// number external references to item 

// (not generally interesting to subclasses) 

// item's horizontal and vertical baseline 

// (currently only the y value is used) 

// window relative bounds 
// (with respect to its bounds' origin) 

// data object that item is in 

// see msgNPItemSetAdjunct for more information 

// item's pen style 
} NP ITEM METRICS, *P NP ITEM METRICS; 



U8 


selected: 


1, 




marked: 


1, 




reserved: 


6; 


U8 


refCount; 




xYie 


baseline; 




RECT32 


bounds ; 




OBJECT 


data; 




OBJECT 


adjunct; 




U32 


penStyle; 





msgNPItetnSetBaseline 

Sets receiver's baseline. 

Takes P_XY32, returns STATUS. 

#define msgNPItemSetBaseline MakeMsg(clsNPItem, 21) 



264 PENPOINT API REFERENCE 

Part 9 / Utility Classes 



msgNPItemSetBounds 

Sets receiver's bounds. 

Takes P_RECT32, returns STATUS. 

#define msgNPItemSetBounds MakeMsg(clsNPItem, 30) 



msgNPItemHold 

Increments the reference count for the item. 
Takes NULL, returns STATUS. 

tdefine msgNPItemHold MakeMsg(clsNPItem, 22) 
Comments When the reference count for an item drops to zero, it is destroyed. 

msgNPItemRelease 

Decrements the reference count for the item. 
Takes NULL, returns STATUS. 

tdefine msgNPItemRelease MakeMsg(clsNPItem, 23) 
lertts When the reference count for an item drops to zero, it is destroyed. 



msgNPItemAlignToBaseline 

Moves item so that it align to passed in line spacing. 

Takes P_XY32, returns STATUS. 

tdefine msgNPItemAlignToBaseline MakeMsg(clsNPItem, 33) 

The item should be aligned against the y-value of pArgs. 

Messages that are usually overridden by 
subclasses 

msgNPItemPaint 

Paints item using the passed in drawing contexts. 

Takes P_NP_ITEM_DC, returns STATUS. 

tdefine msgNPItemPaint MakeMsg{clsNPItem, 12) 

Message typedef struct { 

irgymersfs OBJECT dc; // DC to paint into 

OBJECT dcPen; // equivalent DC in pen units 

} NP_ITEM_DC, *P_NP_ITEM_DC; 

msgNPItemSetPenStyle 

Sets the item's pen style. (Pen styles are defined in notepapr.h.) 

Takes U32, returns STATUS. 

tdefine msgNPItemSetPenStyle MakeMsg(clsNPItem, 34) 
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msgNPItemSetOrigin 

Set receiver's origin. 

Takes P_XY32, returns STATUS. 

tdefine msgNPItemSetOrigin MakeMsg(clsNPItem, 18) 

msgNPItemScratchOut ^ 

lU 

Handles the scratch-out gesture on an item. jg 

Takes P_RECT32, returns STATUS. ^ 

♦define msgNPItemScratchOut MakeMsg(clsNPItem, 24) p 

Scribble items handle this message by deleting strokes that overlap pArgs. Other items simply delete ^ 

themselves. \t^ 

msgNPItemSplitGesture 

Handles the split gesture on an item. 
Takes P_XY32, returns STATUS. 

♦define msgNPItemSplitGesture MakeMsg(clsNPItem, 25) 
Comments The pArgs refers to the "hot point" for the gesture. 

msgNPItemSplit 

Split an item into its constituent items. 

Takes NULL, returns STATUS. 

tdefine msgNPItemSplit MakeMsg(clsNPItem, 26) 

msgNPItemSplitAsWords 

Splits receiver into words. Deletes receiver, inserts new items. 
Takes NULL, returns STATUS. 

#define msgNPItemSplitAsWords MakeMsg(clsNPItem, 16) 

stsItemNoSplit Returned if nothing was split. 

msgNPItemJoin 

Joins receiver and OBJECT and deletes OBJECT. 

Takes OBJECT, returns STATUS. 

#define msgNPItemJoin MakeMsg(clsNPItem, 27) 

msgNPItemTie 

Joins OBJECT and receiver and deletes them. Inserts new object. 

Takes OBJECT, returns STATUS. 

♦define msgNPItemTie MakeMsg(clsNPItem, 17) 
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msgNPItemGetScribble 

Pass back the item's scribble. 
Takes P_OBJECT, returns STATUS. 

#define msgNPItemGetScribble MakeMsg(clsNPItem, 4) 

C®m»iierjts Subclasses that do not contain a scribble should not respond to this message. 

msgNPItemGetString 

Passes back the text string for the item. 
Takes PP_STRING, returns STATUS. 

tdefine msgNPItemGetString MakeMsg(clsNPItem, 38) 

Cammersts Subclasses that do not have a text representation should not respond to this message. 

clsNPScribbleltem responds to this message by translating its scribble and returning the resulting string 
The sender of this message should either use the passed back string immediately or make a copy of it. 

msgNPItemSetString 

Sets the text string for the item. 
Takes P_STRING, returns STATUS. 

#define msgNPItemSetString MakeMsg(clsNPItem, 42) 

Commarsfs Not all items can handle this message. 

msgNPItemToText 

Item converts itself to a text item, passes back text item. 

Takes P_OBJECT, returns STATUS. 

#define msgNPItemToText MakeMsg(clsNPItem, 7) 

Receiver deletes itself from its data and inserts the text item. If pArgs is pNull, the text item is not 
passed back. 

msgNPItemToScribble 

Item converts itself to a scribble item. 
Takes P_ARGS, returns STATUS. 

tdefine msgNPItemToScribble MakeMsg(clsNPItem, 36) 
Con^matsts Receiver deletes itself from its data and inserts the scribble item. 



msgNPItemHitRegion 

Returns stsOK if receiver's path overlaps pArgs. 

Takes P_RECT32, returns STATUS. 

tdefine msgNPItemHitRegion MakeMsg(clsNPItem, 10) 
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Comments 



msgNPItemCalcBaseline 

Calculate and set receiver's baseline. 

Takes P_XY32, returns STATUS. 

tdefine msgNPItemCalcBaseline MakeMsg(clsNPItem, 28) 

The calculation is based on the line spacing specified by pArgs. 



msgNPItemCalcBounds 

Receiver calculates and sets its new bounds. 

Takes OBJECT, returns STATUS. 

tdefine msgNPItemCalcBounds MakeMsg(clsNPItem, 37) 

Comments Usually send in response to the item's style changing. OBJECT is the data object in which the item will be 

inserted. If the item is in a data object, pArgs can be pNull. 



msgNPItemGetWordSpacing 

Receiver passes back the size of its "space" character. 
Takes P_U16, returns STATUS. 

♦define msgNPItemGetWordSpacing MakeMsg(clsNPItem, 43) 
Comments This message is used by msgNotePaperTidy to determine the spacing of items. 



msgNPItemCanBeTranslated 

Receiver returns stsOK if it can be translated. 
Takes pNull, returns STATUS. 

tdefine msgNPItemCanBeTranslated MakeMsg(clsNPItem, 13) 
Comments Translation occurs in response to msgNPItemToText. 

msgNPItemCanBeUntranslated 

Receiver returns stsOK if it can be untranslated. 
Takes pNull, returns STATUS. 

tdefine msgNPItemCanBeUntranslated MakeMsg(clsNPItem, 31) 
Commerits Untranslation occurs in response to msgNPItemToScribble. 
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NPSCR.H 



This file contains the API definition for clsNPScribbleltem. 

clsNPScribbleltem inherits from clsNPItem. 

NPScribbleltem is the ink class of PenPoint's ink-management or note-taking building block. (See 
notepapr.h for more information on the building block.) NPScribbleltem overrides NPItem messages as 
is appropriate. See npitem.h for details. 

tifndef NPSCR_INCLUDED 
tdefine NPSCR_INCLUDED 

tifndef NPITEM_INCLUDED 
♦include "npitem.h" 
#endif 



Types and Constants 



♦define clsNPScribbleltem 



MakeGlobalWKN (2570, 1) 



Messages 



msgNewDefaults 

Initialize pArgs. Zeros out pArgs->scribbleItem. 
Takes P_NP_SCRIBBLE_ITEM_NEW, returns STATUS. 

typedef struct NP_SCRIBBLE_ITEM_NEW_ONLY { 

OBJECT scribble; 

OBJECT data; // data that item will be associated with 

S32 sparel; 

} NP_SCRIBBLE_ITEM_NEW_ONLY, *P_NP_SCRIBBLE_ITEM_NEW_ONLY; 

♦define npScribbleltemNewFields \ 

npItemNewFields \ 

NP_SCRIBBLE_ITEM_NEW_ONLY scribbleltem; 

typedef struct NP_SCRIBBLE_ITEM_NEW { 

npScribbleltemNewFields 
} NP SCRIBBLE ITEM NEW, *P NP SCRIBBLE ITEM NEW; 
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NPTEXT.H 



This file contains the API definition for clsNPTextltem. 

clsNPTextltem inherits firom clsNPItem. 

NPTextltem is the text class of PenPoint's ink-management or note-taking building block. (See 
notepapr.h for more information on the building block.) NPTextltem overrides NPItem messages as is 
appropriate. See npitem.h for details. 

#ifndef NPTEXT_INCLUDED 
tdefine NPTEXT_INCLUDED 
#ifndef NPITEM_INCLUDED 
#include "npitem.h" 
#endif 



Types and Constants 



♦define clsNPTextltem 



MakeGlobalWKN (2571, 1) 



Messages 



Irguments 



msgNewDefaults 

Initialize pArgs. Zeros out pArgs->textItem. 
Takes P_NP_TEXT_ITEM_NEW, returns STATUS. 

typedef struct NP TEXT ITEM NEW ONLY { 



OBJECT 


text; 


P STRING 


pString; 


OBJECT 


data; 



S32 



spare 1; 



} NP_TEXT_ITEM_NEW_ONLy, 

#define npTextltemNewFields 
npItemNewFields 
NP TEXT ITEM NEW ONLY 



// string object 

// string if string object not given 

// data that item will be associated with 

// (item's size measured using data's DC) 

*P NP TEXT ITEM NEW ONLY; 



\ 



\ 



_ _ _ _ text Item; 

typedef struct NP_TEXT_ITEM_NEW { 

npTextltemNewFields 
} NP TEXT ITEM NEW, *P NP TEXT ITEM NEW; 
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ORDSET.H 



This file contains the API definition for the OrderedSet interface. The functions described in this file are 
contained in MISC.LIB. 



Overvlevsf 

An OrderedSet implements a growable, ordered set of items. Each item has a key and associated data. 
The ordered set knows about the structure of the key, but treats the data as uninterpreted bytes. The 
items in an ordered set are homogeneous: there is only one size for the key, and another size for the data, 
for all the items in the set. 

Keys are unsigned quantities, treated as either non-negative integers or indirect access identifiers. The 
client specifies: 

how keys are treated - direct or indirect; 

for indirect keys - access and comparison fiinctions; 

whether duplicate keys are allowed; 

the key size - it must be 1, 2, or 4 bytes. 

The data size (in bytes) is also specified by the client; it must be less than or equal to 1023. 

The client provides an initial estimate of the number of items in the ordered set when the set is created; 
the set will allocate more memory if the estimate proves to be too small. 

Performance considerations 

The implementation of OrderedSet builds on the ByteArray storage abstraction. This implies that either 
the number of elements in the set is small enough that it is not a problem to use a linear array 
representation for the set, or that the number of lookups dominates the number of insertions and 
deletions. 



Indirect Keys and T>vo Comparison Routines 

Ordered sets with indirect keys have a fiinny property. If you want to search for a key that already exists 
in the set, everything's just fine. But if you want to do something with a key that ISN'T in the set (e.g. 
find out if the key is in the set), there is no indirect key to use. (This problem also arises when clients ask 
ordered sets questions such as "What's the next entry with a key greater than this key k?") 

To solve this problem, indirect-keyed ordered sets must be provided two comparison routines by the 
creator. The first routine (passed as the compareKeyl Indirect in a called to OrderedSetExtendO) is used 
when the implementation needs to compare two keys that are both in the set. The second routine 
(passed as compareKeyl Direct in a call to OrderedSetExtendO) is used when the implementation needs 
to compare two keys, only one of which is in the set. 

Caution: 
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If keys are indirect, OrderedSetFindMinMaxO, OrderedSetFindMaxMin(), and OrderedSetNext() 
return the indirect key, not the value the key references. 



KnovN^n Limitations 

This package does not work correctly if the set has indirect keys and (zero) is a legitimate key value. 

tifndef ORDSET_INCLUDED 

tdefine ORDSET_INCLUDED $Revision: 1.17 $ 

#include <bytarray.h> 

♦include <gosearch.h> // For ACCESS/COMPARE FUNC 



Private 



ctlon Prefefype 



typedef U32 (CDECL *READ_KEY_FUNC) ( 
P_ORDERED_SET p, 
P_UNKNOWN pKey) 

typedef struct ORDERED SET { 



U16 


indirectKeys 


1; 


U16 


uniqueKeys 


1; 


U16 


spare 


2, 


U16 


sizeofKeyMinusl 


2; 


U16 


sizeofData 


10; 


P_BYTE_ARRAY 


items; 


ACCESS FUNC 


access; 


COMPARE_FUNC 


compareKeylDirect ; 


COMPARE_FUNC 


compareKeyl Indirect ; 


P_UNKNOWN 


context; 


READ_KEY_FUNC 


readKey; 


} ORDERED SET; 







// TRUE => no duplicate keys 

// Always set to 

// Number of bytes -1 a key needs 

// Number of bytes data occupies 

// Storage of actual items 



// 1st arg to access () & compare!) 
// For internal use only! 



Comiiieiifs 



OrderedSetCountlnternal 

Returns the number of items currently stored in the ORDERED_SET. 
Returns BYTEJNDEX. 

#define OrderedSetCountlnternal (p) \ 

(ByteArray Length (p->items) / OrderedSetSizeofltem(p) ) 

High-performance version of OrderedSetCount, but subject to change if the implementation of ordered 
sets changes. 



Types and Constants 



tdefine stsOrdSetDuplicateKey MakeStatus (clsMisc, 1) 
tdefine findNextKeylnOS ( (P_UNKN0WN)1) 
tdefine findPreviousKeylnOS ( (P_UNKN0WN)2) 
typedef struct 0S_ITEM_INF0 { 

U32 key; 

P_UNKNOWN data; 

BOOLEAN isDuplicate; 
} OS ITEM INFO, *P OS ITEM INFO; 
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OrderedSetPrint 

In debugging version, prints the contents of the ordered set. 
Returns void. 

#ifdef DEBUG 

void EXPORTED S 

Function Prototype OrderedSetPrint { 2 

P_ORDERED_SET p) ; 
#endif // DEBUG 

Comtneots This function is undefined in the non-debugging version. 

OrderedSetCreate 

Creates an ordered set. 
Returns STATUS. 

STATUS EXPORTED 

Fyncflon Prototype OrderedSetCreate ( 

P_ORDERED_SET * pp, 

OS_HEAP_MODE mode, 

U8 sizeofKey, 

U8 sizeofData, 

U32 initialCount, 

BOOLEAN uniqueKeys, 

BOOLEAN indirectKeys) ; 

Comments sizeofKey and sizeofData specify the size in bytes of each item's key and data, respectively. The 

initialCount is a hint; the ordered set will grow or shrink as needed. However, if initialCount is 
approximately correct, performance will be better. If imtialCount=0, 1 will be assumed. uniqueKeys 
should be TRUE if client wants all keys in the set to be unique, FALSE otherwise. Only the 
osHeapLocal / osHeapShared flags in mode are used. 

Returns stsOK if able to create the set, in which case *pp will be the created set, otherwise *pp will be 
Nil(P_ORDERED_SET) . 

OrderedSetSizeofKey 

Returns the size of a key in bytes. 

Returns U16. 

tdefine OrderedSetSizeofKey (p) ( (U16) ( {p)->sizeofKeyMinusl + 1)) 

OrderedSetSizeofltem 

Returns the size of an item (key plus data) in bytes. 
Returns U16. 

tdefine OrderedSetSizeofltem (p) \ 

( (U16) (OrderedSetSizeofKey (p) + (p) ->sizeofData) ) 
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OrderedSetHeapMode 

Returns the heap mode with which the Ordered Set was created. 
Returns OS_HEAP_MODE. 

#cief ine OrderedSetHeapMode (p) ByteArrayHeapMode ( (p) ->items) 

OrderedSetExtend 

Modifies the functions and context of an ordered set with indirect keys. 
Returns STATUS. 

void EXPORTED 

Function Prototype OrderedSetExtend ( 

P_ORDERED_SET p, 

ACCESS_FUNC access, 

COMPARE_FUNC compareKeylDirect, 

COMPARE_FUNC compareKeyl Indirect, 

P_UNKNOWN context) ; 

CmnnwMfs Specifies access and comparison functions for an ordered set with indirect keys, as well as a context for 

those functions. 

See gosearch.h's description of binarySearchQ for more information about the behaviors and parameters 
of the access and compare fimctions. 

OrderedSetContext 

Get the context passed to access and compare functions. 

Returns P_UNKNOWN. 

tdefine OrderedSetContext (_p) ( (_p)->context) 



OrderedSetModifyContext 

Modify the context passed to access and compare functions. 

Returns void. 

tdefine OrderedSetModifyContext {_p, _c) ( (_p) ->context = (_c) ) 

OrderedSetDefaultAccess 

Can be used as the client-specified access routine in OrderedSetExtendQ. 
Returns P_UNKNOWN. 

P_UNKNOWN CDECL 

Fimefion Prototype OrderedSetDefaultAccess ( 

const P_ORDERED_SET p, 
const ByTE_INDEX index); 

c^mmcRts In ordered sets with indirect keys the client must supply a routine that returns the address of the keys 

that are passed into the client-supplied comparison routine. OrderedSetDefaultAccess computes the 
address of the key in the ordered set representation, and so may be used by clients as the access routine 
passed into OrderedSetExtendQ. 
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OrderedSetDestroy 

Destroys an ORDERED_SET. 

Returns void. 

void EXPORTED 

Fyncfion Prototype OrderedSetDestroy ( 

P ORDERED SET p) ; 



OrderedSetlnsert 3 

Inserts data with key into ordered set. = 

Returns STATUS. ^ 

STATUS EXPORTED 



Fyfictiori Protolype C 


rderedSetlnsert ( 






P ORDERED SET 


P/ 




U32 


key, 




P UNKNOWN 


data) ; 



Copies sizeofData bytes from the buffer pointed to by data. Returns: 

stsOSOutOfMem if no memory available, or 

stsOrdSetDuplicateKey if key is duplicate and unique keys required, or 

stsOK otherwise. 

If sizeoflCey is less than 4 bytes, the least significant byte(s) of key are copied. 

OrderedSetNthltem 

Locates the n-th item in the ordered set (item indices begin with 0). 
Returns P_UNKNOWN. 

P_UNKNOWN EXPORTED 

Fyncfion Prototype OrderedSetNthltem ( 

P_ORDERED_SET p, 

U32 n, 

P_OS_ITEM_INFO info) ; 

Comments Returns a pointer to ordered set's copy of the data associated with the Nth item. This pointer is only 

valid until the next call on the same set. 

Upon return, the following modifications have been made to the fields of info: 

key key of nth item 

isDuplicate is not set; use OrderedSetFind() if needed; 

data duplicate of return value 



OrderedSetltemlndex 

Returns the index of an item 
Returns BYTEJNDEX.. 

#define OrderedSetltemlndex (p, pData) \ 

( (ByteArrayFindlndex ( (p) ->items, ( (P_U8) (pData) ) ) \ 
- OrderedSetSizeofKey(p) ) / OrderedSetSizeofltem(p) ) 
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OrderedSetFind 

Locates the data for a specified key. 

Returns P_UNKNOWN. 

P_UNKNOWN EXPORTED 

Function Frofotype OrderedSetFind ( 

P_ORDERED_SET p, 
P_OS_ITEM_INFO info) ; 

Comments Returns a pointer to ordered set's copy of the data associated with info->key. This pointer is only valid 

until the next call on the same set. If the info->key is not in the set, the returned value is 
Nil(P_UNKNOWN). If duplicate copies of the key exist in the set, an arbitrary item is found and its data 
returned. All of the other items with the same key may be examined via use of OrderedSetNext(). Upon 
return, the following modifications have been made to the fields of info: 

isDupIicate if key is unique in set, 1 otherwise 

data duplicate of return value 

OrderedSetFindMinMax 

Locates the data for a key >= to specified key. 

Returns P_UNKNOWN. 

P_UNKNOWN EXPORTED 

Faiicflon Prototype OrderedSetFindMinMax ( 
P_ORDERED_SET p, 
P_OS_ITEM_INFO info) ; 

Comments Returns a pointer to ordered set's copy of the data associated with the minimum key in the ordered set 

that is >= info->key. If info->key is in the ordered set, this routine is equivalent to OrderedSetFind(). 
This pointer is only valid until the next call on the same set. Returns Nil(P_UNKNOWN) if info->key has 
no minmax in the set. If duplicate copies of the minmax key exist in the set, an arbitrary item is found 
and its data returned. All of the other items with the same key may be retrieved with OrderedSetNext(). 
Upon return, the following modifications have been made to the fields of info: 

key minmax key 

isDupIicate if key is unique in set, 1 otherwise 

data duplicate of return value 

OrderedSetFindMaxMin 

Locates the data for a key <= to specified key. 

Returns P_UNKNOWN. 

P_UNKNOWN EXPORTED 

Fsinctlon Prototype OrderedSetFindMaxMin ( 
P_ORDERED_SET p, 
P_OS_ITEM_INFO info) ; 

Comments Returns a pointer to ordered set's copy of the data associated with the maximum key in the ordered set 

that is <= info->key. If info->key is in the ordered set, this routine is equivalent to OrderedSetFind(). 
This pointer is only valid until the next call on the same set. Returns Nil(P_UNKNOWN) if info->key has 
no maxmin in the set. If duplicate copies of the maxmin key exist in the set, an arbitrary item is found 
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and its data returned. All of the other items with the same key may be retrieved with OrderedSetNextQ. 
Upon return, the following modifications have been made to the fields of info: 

key maxmin key 

isDuplicate if key is unique in set, 1 otherwise 

data duplicate of return value 



OrderedSetNext g 

< 

Enumerates the data for keys in the Ordered Set. u 

>- 
Returns P_UNKNOWN. 5 

P_UNKNOWN EXPORTED ^ 

» 
Fynctioo Prototype OrderedSetNext ( i^h 

P_ORDERED_SET p, 
P_OS_ITEM_INFO info) ; 

Comments OrderedSetNextQ's behavior depends on whether the set has unique keys or not. In both cases, the 

enumeration is guaranteed to be complete provided no insertions or deletions are performed on the 
set during the enumeration. 

♦ IF THE SET HAS UNIQUE KEYS 

OrderedSetNextO enumerates all of the keys in the set in order. 

The first item in the enumeration can be found by either (1) by calling OrderedSetNthltemQ with 
an "N" of or (2) calling OrderedSetNextQ with info->data set to Nil and info->key set to the 
lowest possible key value. 

♦ IF THE SET DOES NOT HAVE UNIQUE KEYS 

OrderedSetNextO enumerates all of the keys with the same value. The order of enumeration is 
unspecified. 

The first item with a known key can be found by either (1) by calling OrderedSetFind with 
info->key set to the known key value and info->data set to Nil 

♦ IN BOTH CASES 

Further items are found by calling OrderedSetNextQ with the same info struct until it returns Nil. 
OrderedSetNextQ returns a pointer to the set's copy of the data associated with key. This pointer is 
only valid until the next call on the same set. 

Returns 

Nil(P_UNKNOWN) if specified key not in set or the enumeration is complete, or 

pointer to set's copy of data or if key is in set or enumeration is incomplete. 

Upon return, the following modifications have been made to the fields of info: 

key: next key value, iff info->data had been one of the 

three special values: Nil, next, prev. 
isDuplicate: if key is unique in set, 

1 otherwise 
data: duplicate of returned value 
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♦ FOR SETS WITH DIRECT, NON-DUPLICATE KEYS ONLY 

If the set has direct keys, setting info->data to findNextKeylnOS (findPreviousKeylnOS), 

OrderSetNextO can be used to enumerate all items in the set in order of increasing (decreasing) key 
value. Such an enumeration (assuming non-unique keys) will have the structure: 

info. key = 0; 

info. data = Nil (P_UNKNOWN) ; 

if ((firstData = OrderedSetNext (...)) == Nil (P_UNKNOWN) ) { 

info. data = findNextKeylnOS; 

if ( (firstData = OrderedSetNext (...)) == Nil (P_UNKNOWN) ) { 
// handle empty set 

} 
} 
// firstData and info now contain first item' s information 

// enumerate all keys 
do { 

// enumerate all data with the same key 

while (OrderedSetNext (...)) { 

}; 

info. data = findNextKeylnOS; 
} until ( ! OrderedSetNext (...)); 

OrderedSetEachltem 

Helper macro to simplify the enumeration of an Ordered Set. 

Returns P_UNKNOWN. 

fdefine OrderedSetEachltem (_p, _item) \ 

for ((_item).key = (U32)0, (_item) .data = Nil (P_UNKNOWN) ; \ 
OrderedSetNext ( (_p) , & (_item) ) ! = Nil (P_UNKNOWN) ; ) 
// The condition IS the iteration step 

This macro is only useful for sets with direct, non-duplicate keys! 

The arguments to OrderedSetEachItem() are: 

_p the ordered set to enumerate 

_item an OS_ITEM_INFO containing the enumerated item's info 

Code using these macros should look like: OS_ITEM_INFO scratch; OrderedSetEachItem(os, scratch) { 
myPtr = (MY_PTR)scratch.data; ... } 



OrderedSetDelete 

Deletes specified item from the Ordered Set. 
Returns STATUS. 

STATUS EXPORTED 

Fonct!0ri Prototype OrderedSetDelete ( 

P_ORDERED_SET p, 
P_OS_ITEM_INFO info) ; 

Commetits If duplicates are allowed, both info->key and info->data must be filled in by client; if keys are unique, 

only info->key need be filled in. 
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Returns: 

stsOK if item was found in set and deleted, or 
stsNoMatch if item not found in set, or 
STATUS < if internal error during deletion. 



Foncfion Prototype 



OrderedSetCount 

Returns the number of items currently stored in the ORDERED_SET. 

Returns U32. 

U32 EXPORTED 

OrderedSetCount ( 

P_ORDERED_SET p) ; 
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This file contains the API definition for clsQuickHelp. 

clsQuickHelp inherits firom clsFrame. 

clsQuickHelp provides an interface to the Quick Help Server. 

theQuickHelp is a well-known instance of clsQuickHelp. 

theQuickHelp provides system wide quick help, and is the only instance of clsQuickHelp in the system, 
built at boot time. Clients should not create instances of this object, nor should they subclass this object. 
This file defines an interface to display quick help text in the standard quick help window. Programmers 
should rarely have to call ANY of the fiinctions in this file, as default calling of quick help is provided by 
default in clsGWin (see gwin.h). However, some applications may need to invoke quick help, or change 
the quick help text, hence the public message to open quick help, and to show a quick help screen. 

A quick help resource consists of a string array resource with each array item mapping to a single quick 
help panel. This resource is identified by creating a List resource ID from the administered portion of 
the quick help ID (MakeListResId(helpID, resGrpQhelp, 0)) and the quick help group. The TAG 
portion of the quick help ID is used to index into the string array. Each quick help strings will have two 
"parts". The first part will be the title and the second part will be the text. The title will be separated 
from the text by including two vertical line characters (II) following the title which will NOT be printed. 

These resources, which are defined below, are put into the application resource files and displayed using 
msgQuickHelpShow, which takes the resource ID. As mentioned, gWin defines a default behavior for 
calling the object with this message. All application typically need to do is provide their gWin objects 
(or subclasses) with helpid resources. 

Quick help for an object is generally displayed in one of two ways. The first is when an object decides to 
display quick help for itself An example is gWin s response to the '?' gesture. gWin posts theQuickHelp 
msgQuickHelpShow, which opens the quick help window and displays quick help for the object. The 
second is when theQuickHelp window is open, and the system is in quick help mode. When the user 
taps on objects on the screen, the object is sent msgQuickHelpHelpShow. The object will respond by 
posting msgQuickHelpShow back to theQuickHelp. When the quick help window is dismissed, by 
hitting closed or envoke help notebook, the object that received msgQuickHelpHelpShow will receive 
msgQuickHelpHelpDone. This message will also be sent when tapping on successive objects while in 
quick help mode. It will not be sent when quick help was initially brought up directly from the object 
when it posted msgQuickHelpShow (such as the gWin response to the '?' gesture. 

tifndef QHELP_INCLUDED 
tdefine QHELP_INCLUDED 

tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 

tifndef CLSMGR_INCLUDED 
tinclude <clsmgr.h> 
tendif 

tifndef RESFILE_INCLUDED 
tinclude <resfile.h> 
tendif 
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Debugging Flags 

Quick Help uses the debugging flag set 'q'. Defined flags are: 
0001 General quick help debugging information 

Types and Constants 

These tags are used for defining three quick help screens: 1) the quick help intro screen that gives 
directions on quick help, 2) the "No help available" screen, and 3) the help not found screen. 

#define hlpQuickHelpSignOn MakeTag(clsQuickHelp, 1) 

tdefine hlpQuickHelpNoHelp MakeTag(clsQuickHelp, 2) 

tdefine hlpQuickHelpNotFound MakeTag(clsQuickHelp, 3) 



Messages 



msgQuickHelpShow 

Displays the Quick Help associated with the resource ID. 

Takes P_QUICK_DATA, returns STATUS. 

#define msgQuickHelpShow MakeMsg(clsQuickHelp, 1) 

iments typedef struct QUICK_DATA { 

U32 helpid; // Help ID of the screen to show 

OBJECT appUID; // UID of the application. Used to find resources 

// of application specific help IDs. 
U32 reserved; // Reserved for future use 

} QUICK_DATA, *P_QUICK_DATA; 

menu Gets the quick help resource firom either the system resource files or the application specific resource 

files. If the quick help resource can't be found, will display the "Quick help not found" message in the 
quick help screen. Typically called firom gWin in order to display the help screen for a help gesture. 
Would take the gWin helpid and the application uid. Needs the application object in order to reference 
the resource files of the application to find application specific help IDs. Typically not called directly by 
applications, but called indirectly through gWin inheritence. Will call msgQuickHelpOpen to open the 
quick help window as necessary. 

Typically called by objects in response to a ? gesture, or in response to msgQuickHelpHelpShow. 

Also gwin.h 

msgQuickHelpHelpShow 

Sent to a window to display a quick help request. 

Takes P_XY32, returns STATUS. 

tdefine msgQuickHelpHelpShow MakeMsg(clsQuickHelp, 7) 

rnents Sent from theQuickHelp to a window when it is required to display its quick help. Typically the 

window will respond by posting msgQuickHelpShow. Sent as the user taps on various windows while 
quick help is being displayed. 

Also msgQuickHelpHelpDone 
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msgQuickHelpHelpDone 

Sent to a window when quick help is no longer displayed. 

Takes OBJECT, returns STATUS. 

tdefine msgQuickHelpHelpDone MakeMsg(clsQuickHelp, 8) 

Comments Sent to the last object asked to display quick help via msgQuickHelpHelpShow when help is no longer 

needed on said object. Can be sent because the user tapped somewhere else and a new object is about to 
be sent msgQuickHelpHelpShow, quick help has been terminated by the user, or the help notebook has 
been entered. Takes the new object receiving a msgQuickHelpHelpShow if because the user tapped B 

elsewhere, or null if quick help is being terminated or going to the help notebook. Note that this 
message is only sent to object which previously received msgQuickHelpHelpShow, and not those 
objects generating a help request by posting msgQuickHelpShow directfy^. 

See Also msgQuickHelpHelpShow 

msgQuickHelpOpen 

Forces the Quick Help window to appear. 

Takes nothing, returns STATUS, 

tdefine msgQuickHelpOpen MakeMsg(clsQuickHelp, 2) 

Comments Opens the quick help window on the screen. If the quick help window is already on the screen, will 

simply return stsOK. The quick help window is a modal filter that will grab all input till closed via 
msgQuickHelpClose. Self sent to when msgQuickHelpShow is posted. Also sent from the help 
notebook icon to invoke quick help. 

W Notification Messages 



msgQuickHelpOpened 

Indicates that the quick help window has been opened. 
Takes nothing, returns STATUS. Category: observer notification, 
tdefine msgQuickHelpOpened MakeMsg{clsQuickHelp, 128) 

ZommenH Sent to observers of the quick help that the quick help window has been opened. 



msgQuickHelpClosed 

Indicates that the quick help window has been closed. 
Takes nothing, returns STATUS. Category: observer notification, 
tdefine msgQuickHelpClosed MakeMsg(clsQuickHelp, 129) 

Comments Sent to observers of theQuickHelp to indicate that the quick help window has been closed. 

msgQuickHelpInvokedNB 

Indicates that the notebook associated with quick help should be open. 
Takes nothing, returns STATUS. Category: observer notification, 
tdefine msgQuickHelpInvokedNB MakeMsg(clsQuickHelp, 130) 
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smmeRfs Sent to observers when msgQuickHelpInvokeNB is recieved. The help note book is an observer, and 

will bring itself up when this message is recieved. 
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SEL.H 



This file contains the API for clsSelection. 

clsSelection inherits from clsObject. 

theSelectionManager provides management of the system-wide selection. theSelectionManager is the 
one and only instance of clsSelection. 

Introduction 

Much of PenPoint's user interface is based on the "selection." The selection is often the center of the 
user's attention. In general it is very easy for the user to set the selection ~ it often just requires a tap. 

The precise definition of the selection is application-specific. In text the selection is often a set of 
characters. In a spreadsheet it might be a range of rows, columns, or cells. In a Table of Contents it 
might be a set of documents. Typical^, an application "highlights" the selection with a grey background, 
handles, or some other graphic technique. 

Because the selection corresponds to the center of the user's attention, many user interface operations are 
based on the selection. Here are some examples: 



The selection is the source of PenPoint's move and copy operations. 

Typically, the selection is altered by Applying an Option Sheet. 

The selection often determines which menu items are enabled and which are disabled. 

The selection and keyboard input target are often linked together. 

Programmatical^, other objects can inquire about the selection, get information from the selection and 
transfer data from the selection. 



Road Mop 



Use the following to take ownership of the selection: 

♦ msgSelSetOwner 

♦ msgSelSetOwnerPreserve 

♦ msgSelSelect (if object has clsEmbeddedWin in the object's ancestry) 
Selection owners must be prepared to handle the following: 



msgSelDelete 

msgSelYield 

msgSelBeginCopy 

msgSelBeginMove 

msgControlProvideEnable (see section "Control Enabling") 
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Use the following to inquire about the selection: 

♦ msgSelOwner 

♦ msgSelPrimaryOwner 

♦ msgSelOwners 

♦ msgSellsSelected (if object has cIsEmbeddedWin in the object's ancestry) 
theSelectionManager sends the following notifications: 

♦ msgSelChangedOwners 

♦ msgSelPromotedOwner 

Destinations of PenPoint's Move and Copy mechanism must handle the following: 

♦ msgSelCopySelection 

♦ msgSelMoveSelection 



Move and Copy 



sel.h defines several messages that are used to implement PenPoint's Move and Copy operations. These 
messages are used in combination with PenPoint's data transfer messages which are defined in xfer.h. 
(PenPoint data transfer does not always necessarily involve the selection, but when it does, the messages 
described here are employed.) 

cIsEmbeddedWin (see embedwin.h) provides the default response for several of the steps described 
below. 

Here's the typical "flow of control" for moving selected data: 

♦ The source object handles the "Press" gesture (xgsPressHold in xgesture.h). The object might 
receive this gesture if it is a gWin (see gwin.h). 

♦ If the Press gesture is not over the selection, the object typically selects what is under the gesture. 
"Selecting" includes either (1) self sending msgSelSelect or (2) sending msgSelSetOwner to 
theSelectionManager, whichever is appropriate, 

♦ Next the object self-sends msgSelBeginMove. 

♦ msgSelBeginMove is received. Note that msgSelBeginMove is sent in other cases than the Press 
gesture response. For instance, the standard application menu item "Move" (in the "Edit" menu) 
results in the selection owner receiving msgSelBeginMove. 

♦ In response to msgSelBeginMove, the receiver should self send msgEmbeddedWinBeginMove. 
msgEmbeddedWinBeginMove takes, in its pArgs, the hot point of the gesture that kicks off the 
move, and the bounds of the selection being moved. 

♦ In response to msgEmbeddedWinBeginMove, embeddedWin creates the floating "move icon." 
cIsEmbeddedWin manages the icon. 

♦ The icon takes over at this point and manages the process of moving the selection. 

♦ When the icon is dropped on a destination, the icon sends msgMoveCopylconDone to the source. 

♦ cIsEmbeddedWin handles msgMoveCopylconDone and sends msgSelMoveSelection to the 
destination. 
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♦ In response to msgSelMoveSelection, the destination object retrieves the selection owner from the 
selection manager (using msgSelOwner) and engage in an xfer protocol with the selection. (The 
xfer protocols are described in xfer.h) The data should be copied to the position contained in 
msgSelMoveSelection's pArgs, which is a P_XY32. 

♦ After the data has been copied from the selection owner, the destination should send msgSelDelete 
to the selection owner. 

♦ The destination object should select the data that it just absorbed. 

The "flow of control" for copying selected data is very similar, with the following changes: ^ 

u 

♦ The gesture that kicks off the protocol is "Tap-Press" (xgsTapHold in xgesture.h) rather than ^ 
Press-Hold. P 

♦ The source object self sends and handles msgSelBeginCopy rather than msgSelBeginMove. The » 
source object self sends msgEmbeddedWinBeginCopy rather than msgEmbeddedWinBeginMove. ■■■ 

♦ The destination receives msgSelCopySelection rather than msgSelMoveSelection. 

♦ The destination object should not send msgSelDelete. 
Also xfer.h.h 

Tvifo Selection 0>vners 

Some objects need to own the selection, but they need to take in a fashion that (1) allows PenPoint to 
restore the original selection and (2) allows client code to find the original selection. For example, 
Option Sheets apply to a selection. But the various controls that appear within the option sheet might 
need to own the selection as well. Both selections need to be maintained. 

Therefore theSelectionManager actually manages two selection owners: a selection owner and a 
preserved selection owner. 

NOTE: The same object cannot be both the selection owner and preserved selection owner. See the 
detailed comments with msgSelSetOwner and msgSelSetOwnerPreserve for details. 

When an object needs to take the selection but allow the current selection to be restored, that object 
should take the selection via msgSelSetOwnerPreserve, which "preserves" or "remembers" the original 
selection. The preserved selection can be restored by sending msgSelOwnerPreserve with a pArgs of 
pNull to theSelectionManager. Hence objects in option sheets take the selection via 
msgSelSetOwnerPreserve. 

Essentially all clients should operate on the selection owner. This includes move and copy operations. 
The only client that should operate on the preserved selection owner, if one exists, is option sheets. 

Control Enabling 

Some controls, particularly menu items, should be disabled if there is no selection owner. And some 
controls should be disabled based on application-specific details about the selection state. 

For instance, the "Move," "Copy," and "Delete" menu items should not be enabled if there is no 
selection owner. The "Move" menu item should be enabled if there is a selection and the selection owner 
is not read-on]^. The "Delete" menu item should be enabled if there is a selection owner and the 
contents of the selection are not empty. 

To support this, clsControl allows control creators to specify that the control should send 
msgControlProvideEnable to the selection owner to get the proper enable/disable state. 
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Some standard application menus (SAMs) are set up to send msgControlProvideEnable to the selection 
owner. See app.h for details. 

Therefore all selection owners should handle msgControlProvideEnable. 

Relationship of Selection to the input Target 

The input system's "Target" is the object to which keyboard events are sent. See input.h for more 
information. 

Because the selection is normally the center of the user's attention, it often makes sense for the same 
object to own the selection and to be the input target. For instance, PenPoint's text component always 
becomes the input target whenever it takes the selection and sets the input target to null when it yields 
the selection. 

There are, however, cases where it makes more sense to NOT link the selection and input target 
together. For instance, some types of fields take the input target without taking the selection. The 
decision is quite application-specific. 

Implementing a correspondence between the input target and selection ownership is the client's 
responsibility. 

What to Do When the Selection Changes Within an 0>vner 

Some parts of PenPoint's UI depend on knowing when the user's center of attention changes. For 
instance, each time that an Option Sheet is notified that the selection has changed it checks to be sure 
that the top card is still apphcable. 

Therefore, selection owners should set the selection to self EVERY TIME THE SELECTION 
CHANGES within them, even if they are already the selection owner. This lets observers take any 
appropriate action. 

Only One Instance 

There is one and only one instance of clsSelection, and that instance is the global well-known 
theSelectionManager. 

tifndef SEL_INCLUDED 
tdefine SEL_INCLUDED 

tifndef CLSMGR_INCLUDED 
tinclude <clsingr.h> 
#endif 



Common #defines and typedefs 



Status Codes 

theSelectionManager returns stsSelYieldlnProgress when the selection manager is in the process of 
sending msgSelYield and therefore can't respond to the message. 

#define stsSelYieldlnProgress MakeWarning (clsSelection,!) 



Types 
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Messages Sent to theSelectionManager 



preservedOwner is defined only if havePreservedOwner is true. It IS possible to have a null 
preservedOwner. 

typedef struct SEL_OWNERS { 

OBJECT owner; 

OBJECT preservedOwner; 

BOOLEAN havePreservedOwner; 

} SEL OWNERS, *P SEL OWNERS; 



Messages Sent to theSelectionManager 

// Next Up: 26, Recycled: 9, 14, 20 



rufsi •fmi 



msgSelSetOwner 

Sets the selection owner. 

Takes OBJECT, returns STATUS. 

tdefine msgSelSetOwner MakeMsg(clsSelection,2) 

Send msgSelSetOwner to theSelectionManager to set the selection owner. theSelectionManager 
responds in one of the following ways: 

If pArgs is not a valid selection owner (because it can't be called from other objects or is not a global 
object): 

♦ theSelectionManager returns stsScopeViolation. 
If pArgs is null, theSelectionManager: 

♦ sends msgSelYield to the current selection if it exists and sets the current selection to null. 

♦ sends msgSelYield the current preserved selection if it exists and sets the current preserved selection 
to null. 

♦ sends msgSelChangedOwners to theSelectionManager's observers. 
Otherwise, theSelectionManager: 

♦ sends msgSelYield to the current preserved selection if it exists and is not equal to pArgs. 
theSelectionManager then sets the preserved selection to null and stops observing the preserved 
selection. 

♦ sends msgSelYield to the current selection if it exists and is not equal to pArgs. 

♦ sets the current selection to pArgs. 

♦ adds itself as an observer of the new selection. 

♦ sends msgSelChangedOwners to theSelectionManager's observers. 
StsScopeViolation pArgs is not a valid selection owner. 



Ss,i isb.« msgSelYield 



msgSelSetOwnerPreserve 

Sets the selection owner with the preserve option. 
Takes OBJECT, returns STATUS. 

#define msgSelSetOwnerPreserve MakeMsg(clsSelection,5) 
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Costimenfs Send msgSelSetOwnerPreserve to theSelectionManager to set the selection owner while preserving the 

current selection owner. 

See the section "Two Selection Owners" for more information. 

theSelectionManager 's response to this message is similar to its response to msgSelSetOwner, with only 
subtle differences. 

If pArgs is null, and there is no preservedOwner: 

♦ theSelectionManager simply returns stsOK. 

If pArgs is null, and a preserved owner exists (even if it is null), theSelectionManager: 

♦ sends msgSelYield to the current owner if it exists. 

♦ sends msgSelPromote to the current preserved owner if non-null. 

♦ sets the current owner to the current preserved owner if non-null. 

♦ sets the current preserved owner to null. 

♦ sets the value for SEL_OWNERS.havePreservedOwner to false. 

♦ sends msgSelPromotedOwner to theSelectionManager s observers. 

If pArgs is non-null but is not a valid selection owner (because it can't be called from other objects or is 
not a global object): 

♦ theSelectionManager returns stsScopeVioIation. 

If pArgs is a valid selection owner and there is a no preserved owner: 

♦ sends msgSelDemote to the current owner. 

♦ sets the current preserved owner to be the current owner. 

♦ sets the current owner to be pArgs. 

♦ adds itself as an observer of the new selection. 

♦ sets the value for SEL_OWNERS.havePreservedOwner to true. 

♦ sends msgSelChangedOwners to theSelectionManager s observers. 
If pArgs is a valid selection owner and there is a preserved owner: 

♦ sends msgSelYieid to the current owner if it exists and is not the same as pArgs. 

♦ sets the current owner to pArgs. 

♦ adds itself as an observer of the new selection. 

♦ sends msgSelChangedOwners to theSelectionManager 's observers. 
Return Value stsScopeViolation pArgs is not a valid selection owner. 

See Also msgSelYield 



msgSelOwner 

Passes back the selection owner. 

Takes P_OBJECT, returns STATUS. 

tdefine msgSelOwner MakeMsg(clsSelection,l) 



Commetits 



Return Value 



Comments 
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Notifications Sent to theSelectionManager's Observers 

theSelectionManager passes back the current selection owner. It does not pass back the preserved 
selection owner. 

stsSelYieldlnProgress theSelectionManager is currently sending msgSelYield. 

msgSelPrimaryOwner 

Passes back the primary selection owner. 

Takes P_OBJECT, returns STATUS. 

tdefine msgSelPrimaryOwner Ma]ceMsg(clsSelection,7) 

The "primary owner" is the selection owner which an option sheet appHes to. If there is a preserved 
selection owner, the primary owner is the preserved owner. Otherwise, the primary selection owner is 
the current owner. 

StsSelYieldlnProgress theSelectionManager is currently sending msgSelYield. 

msgSelSetOwner 



Wessoge 
^rqumenf 



^;je A;j' 



msgSelOwners 

Passes back the selection and preserved owners. 

Takes P_SEL_OWNERS, returns STATUS. 

tdefine msgSelOwners MakeMsg(clsSelection,4) 

typedef struct SEL_OWNERS { 

OBJECT owner; 

OBJECT preservedOwner; 

BOOLEAN havePreservedOwner; 

} SEL_OWNERS, *P_SEL_OWNERS; 

StsSelYieldlnProgress theSelectionManager is currently sending msgSelYield. 
msgSelSetOwner 



Notifications Sent to tiieSelectionManager^s 
Observers 



msgSelChangedOwners 

Notifies observers when either of the selection owners changes. 

Takes P_SEL_OWNERS, returns STATUS. 

tdefine msgSelChangedOwners MakeMsg(clsSelection, 6) 

Aes&age typedef Struct SEL_OWNERS { 

Irgymetifs OBJECT owner; 

OBJECT preservedOwner; 

BOOLEAN havePreservedOwner; 

} SEL_OWNERS, *P_SEL_OWNERS ; 

:&mments theSelectionManager posts msgSelChangedOwners to its observers to inform the observers that the 

selection owner and/or preserved owner has been set. (The notification is sent even if the new owner 
is null.) 
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theSelectionManager sends this notification even if the old owner and new owner are the same. Hence 
if object A is the selection owner, and msgSelSetOwner is sent with object A, msgSelChangedOwners 
IS sent to theSelectionManager s observers. 

When a preserved selection owner is promoted back to the selection owner, msgSelPromotedOwner is 
sent rather than msgSelChangedOwners. 

Example of use: In response to this message, option sheets check the applicability of the top card. 

Also msgSelSetOwner 

msgSelPromotedOwner 

Notifies observers when the preserved owner has been promoted back to the selection owner. 

Takes P_SEL_OWNERS, returns STATUS. 

tdefine msgSelPromoteciOwner MakeMsg(clsSelection,8) 

ssge typedef struct SEL_OWNERS { 

ittie«ts OBJECT owner; 

OBJECT preservedOwner; 

BOOLEAN havePreservedOwner; 

} SEL_OWNERS, *P_SEL_OWNERS ; 

ittents theSelectionManager posts msgSelPromotedOwner to its observers to inform the observers that 

preserved selection owner has been promoted to the normal selection owner. 

This happens as a result of theSelectionManager handling msgSelSetOwnerPreserve with a pArgs of 
null. 

A?so msgSelSetOwnerPreserve 

Messages Sent by theSelectionManager to 
Ovrners 



msgSelYield 

theSelectionManager requires the release of the selection. 

Takes BOOLEAN, returns STATUS. 

tdefine msgSelYield MakeMsg(clsSelection,ll) 

theSelectionManager sends this message to a selection owner to inform the object that it is no longer 
the selection owner. pArgs is true if object is yielding the primary selection and false when the object is 
yielding the preserved selection. 

This message is not sent when an object takes the selection via msgSelSetOwner or 
msgSelSetOwnerPreserve and it already is the selection, or already is the preserved selection. (However, 
msgSelChangedOwners IS sent to theSelectionManager s observers.) 

When handling this message, be carefiil about sending selection manager messages (such as 
msgSelSetOwner) as deadlock can occur. 

After sending msgSelYield, theSelectionManager removes itself as an observer of the object. 

msgSelSetOwner 
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Embedded Window Messages 



msgSelDemote 

Informs the owner that it is becoming the preserved owner. 

Takes nothing, returns STATUS. 

#define msgSelDemote MakeMsg(clsSelection,24) 

theSelectionManager sends this message to a selection owner to tell the owner that it is becoming the 
preserved owner. (This can happen when theSelectionManager receives msgSeiSetOwnerPreserve.) 

Receivers should not do anything in response to this message. (If for some reason receivers chose to 
handle this message, be careful about sending selection manager messages (such as msgSelSetOwner) as 
deadlock can occur.) 

msgSelPromote 

msgSelPromote 

Informs the preserved owner that it is becoming the owner. 

Takes nothing, returns STATUS. 

#define msgSelPromote MakeMsg(clsSelection,25) 

Comments theSelectionManager sends this message to a preserved selection owner to tell the owner that it is 

becoming the normal selection owner. (This can happen when theSelectionManager receives 
msgSeiSetOwnerPreserve.) 

Receivers should not do anything in response to this message. (If for some reason receivers chose to 
handle this message, be carejfijl about sending selection manager messages (such as msgSelSetOwner) as 
deadlock can occur.) 

See Also msgSelSetOwner 

i Embedded Window Messages 

Most subclasses of clsEtnbeddedWin should use these messages. See embedwin.h for information about 
how and why to use them. 

The messages are defined here rather than in embedwin.h because they are abstract. Theoretically other 
classes can respond to these messages to implement behavior analogous to that of embeddedWin 
(although no other PenPoint system class does so). 

tnsgSelSelect 

Sets self to be the selection owner. 

Takes nothing, returns STATUS. 

tdefine msgSelSelect MakeMsg(clsSelection,19) 

■tommenfs See the section "Embedded Window Selection Messages" for more information. 

Send this message to an object to have that object make itself be the selection owner or the preserved 
selection owner. 

Do not send this message to theSelectionManager. 

See Also msgSelSctOwner.h 
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msgSellsSelected 

Returns TRUE if self is current selection owner. 

Takes nothing, returns BOOLEAN. 

#define msgSellsSelected MakeMsg(clsSelection,21) 
irnents See the section "Embedded Window Selection Messages" for more information. 

Send this message to an object to inquire if it is the selection owner. 

Do not send this message to theSelectionManager. 
irn ¥«i«e true The object is the selection owner. 

false The object is not the selection owner. (The object may be the preserved selection owner.) 
/yso embedwin.h 



Abstract Messages for Selection Move 
& Copy 



msgSelBeginCopy 

Initiate a copy operation. 

Takes P_XY32, returns STATUS. 

#define msgSelBeginCopy MakeMsg(clsSelection, 23) 

romments See the section "Move and Copy" for information about when this message is sent and how it should be 

handled. 

pArgs will be null if this message is sent from a menu. 



msgSelBeginMove 

Initiates a move operation. 

Takes P_XY32, returns STATUS. 

tdefine msgSelBeginMove MakeMsg(clsSelection, 22) 

See the section "Move and Copy" for information about when this message is sent and how it should be 
handled. 

pArgs will be null if this message is sent from a menu. 



msgSelCopySelection 

The receiver should copy the selection to self at (x, y). 

Takes P_XY32, returns STATUS. 

#define msgSelCopySelection MsgNoError(MakeMsg(clsSelection,16) ) 

See the section "Move and Copy" for information about when this message is sent and how it should be 
handled. 
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Abstract Messages For Linking Protocol 



msgSelMoveSelection 

The receiver should move the selection to self at (x, y). 

Takes P_XY32, returns STATUS. 

tdefine msgSelMoveSelection MsgNoError(MakeMsg{clsSelection,15) ) 

:emmetits See the section "Move and Copy" for information about when this message is sent and how it should be 

handled. ^ 

lU 

msgSelDelete " 



The selection owner should delete the selection. 
Takes U32, returns STATUS. 

♦define msgSelDelete MakeMsg{clsSelection,3) 

♦define SelDeleteReselect // Display a selection after delete 

tdefine SelDeleteNoSelect 1 // Don't display a selection after delete 

CommenH Clients wishing to delete the selection send msgSelDelete to the selection owner. Selection owners 

should respond to this message by deleting the contents of the selection. 

msgSelDelete is sent in two situations: (1) the user has hit the "Delete" menu item, or (2) an object has 
received msgSelMoveSelection, has copied the data (see xfer.h), and now wants to delete the original 
data. 

See the section "Move and Copy" for information about how msgSelDelete is related to moving data. 

pArgs must be one of SelDeleteReselect or SelDeleteNoSelect. This parameter is just a performance 
enhancement. The sender of msgSelDelete should pass SelDeleteNoSelect if it plans on taking the 
selection after the msgSelDelete, and SelDeleteReselect otherwise. The receiver of msgSelDelete can use 
pArgs as an optimization, but it is not strictly necessary since theSelectionManager will send a 
msgSelYield when the sender takes the selection. (The pArgs of msgSelDelete exist primarily for 
historical reasons. The simplest thing to do is for the sender to pass SelDeleteReselect and for the 
receiver to ignore pArgs.) 



Abstract Messages For Linking Protocol 



msgSelRememberSelection 

The receiver should "remember" the selection and place the "remembrance" at (x, y). 

Takes P_XY32, returns STATUS. 

♦define msgSelRememberSelection MsgNoError (MakeMsg(clsSelection, 17) ) 

Comments Most objects should not send or handle this message. It might be better defined as a clsEmbeddedWin 

message. 

msgSelRememberSelection is sent to an object to ask it to "remember" the selection. The response to 
this message is highly object specific. 

This message is not sent to the selection owner; it is sent to any object to ask it remember the selection. 

An embeddedWin self sends this message in response to the "Create Reference Button" gesture 
(xgsDbiCircle in xgesture.h). In response, an embeddedWin creates a goto button at the specified (x,y). 

See Also embedwin.h 
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SPELL.H 



Spelling Checking 
proof.h, pdict.h 

tifndef SPELL_INCLUDED 
tdefine SPELL_INCLUDED 

/DSOOOl Low-level debug messages; LOTS of output 
/DS0002 mid-level debug messages 
/DS0004 high-level debugs - general information 
/DS8000 disable dictionary 

tifndef GO_INCLUDED 
tinclude <go.h> 
tendif 



Common Definitions 



max. 



SpellList is the most bytes a list of spelling corrections can use.is the dictionary alphabet size 



tdefine maxSpellList 
#define maxSpellXlateChoices 



128 
30 



Common typedefs 



typedef struct SPELL_LIST { 

U16 count; // Number of strings in the list 

CHAR words [maxSpellList]; // List of concatenated strings 

} SPELL_LIST, * P_SPELL_LIST; 

typedef struct SPELL_XLATE { 

U16 index; // Offset within bank 

U8 bits; // Nibble and bank indicator 

U8 character; // Out: Character at that location 

} SPELL_XLATE, *P_SPELL_XLATE; 

typedef struct SPELL_DICT_LIST { 

P CHAR pName; // name of dictionary (e.g. English) 
P~CHAR pPath; // path to dictionary (e.g. \\boot\dicts\webf77k) 
U16 bankCount; // Number of 16K banks the lex is divided into 
P_UNKNOWN pLangHeader;// Pointer to language specific info 

} SPELL_DICT_LIST, *P_SPELL_DICT_LIST; 

Definitions of different types of word capitalization 

Enuml6(SPELL_CASE) { 

spellCommonCase, // all letters are in lower case 
spellProperCase, // The First Letter Of Each Word Is Capitalized 
spellUpperCase, // ALL LETTERS ARE CAPITALIZED 
spellSpecialCase, // tHere IS a StRANge Mix of cAPitALizATion 

}; 



typedef struct SPELL_CASE_CONTEXT { 

SPELL_CASE minCase; // lowest case allowed for output dictionary words 

SPELL_CASE unkCase; // case for non-dictionary words 

BOOLEAN sentence; //do end-of -sentence processing 

BOOLEAN dictionary; // use the dictionary for capitalization info 

BOOLEAN allCapsWriter; // user writes all caps only 

BOOLEAN firstWord; // In/Out: This word is first in a sentence 



} SPELL_CASE_CONTEXT, * P_SPELL_CASE_CONTEXT ; 
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Functions 



SpellDictSelect 

Sets the active dictionary to the language specified. 

Returns STATUS. 

STATUS EXPORTED SpellDictSelect ( 

S16 dictCode 
); 

dictCode is an index into spellDictList; -1 means deselect. Currently, onlyEnglish can be selected, and 

its code is 0. 



SpellSetOptionsX 

Turns the dictionary on or off. 

Returns void. 

void EXPORTED SpellSetOptionsX (BOOLEAN mode) ; 

Pass it true to turn the dictionary on, false to turn it off. 



SpellGetOptionsX 

Returns current dictionary status. 

Returns BOOLEAN. 

BOOLEAN EXPORTED SpellGetOptionsX (void) ; 
True means spelling is on; false means it's off. 

SpellCheck 

Checks if a word is in the dictionary or not. 

Returns BOOLEAN. 

BOOLEAN EXPORTED SpellCheck (P_CHAR pWord) ; 

Argument may contain punctuation but should not contain spaces. Thisdesigned so higher-level 

software can parse a line of text intotokens and pass those tokens (with no ffirther) to this routine. 

SpellCorrect 

Finds all the corrections for a word and adds them to a SPELL_LIST structure. 
Returns STATUS. 

STATUS EXPORTED SpellCorrect ( 

P_CHAR pWord, // Word to be corrected 

P_SPELL_LIST pSpellList, // Out: List to add the word to 

BOOLEAN phonetic // Perform phonetic correction? 

); 
This also takes a space-delimited token, as described above, stripsthe punctuation, and puts it back on 

the correction candidates. that the count field in the SPELL_LIST structure must beto zero, unless you 

are deliberately adding to anlist. This routine avoids adding duplicates to theif it already had some 

words in it. 
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Functions 



SpellCorrectWord 

Finds the first correction for a word. Returns if none found, else 1 . 

Returns U16. 

Fytiction Prototype U16 EXPORTED SpellCorrectWord ( 

P_CHAR pWord, // Word to be corrected 

P_CHAR pCorrectWord // Out: place to put the correction 
); «. 

lU 

The word is a space-deUmited token, as described above. In this, "first" means "first in alphabetical ^ 

order," this routine issui table for most applications. " 



SpellAddToDict 

Add a word to thePersonalDictionary. 

Returns STATUS. 

Function Prototype STATUS EXPORTED SpellAddToDict ( 
P_CHAR pWord 
); 

Comments The prefered way to add words to the current personal dictionary. As usual, it takes space-delimited 

tokens and strips off extraneous punctuation. 



SpellAddToAnyDict 

Add a word to any one of the personal dictionaries. 

Returns STATUS. 

¥um.fmn Prototype STATUS EXPORTED SpellAddToAnyDict ( 
OBJECT pDict, 
P_CHAR pWord 

); 

Cm-nmmnfs The prefered way to add words to a personal dictionary other than the current one. It takes a pdict 

object (clsPDict) that specifies the personal dictionary to add to, and space-delimited tokens. It strips off 
extraneous punctuation. 

SpellWordSetCase 

Convert all-upper-case input into a reasonable mix of upper and lower case using dictionary information 
and other lexical clues. 

Returns STATUS. 

Fuiiction Prototype STATUS EXPORTED SpellWordSetCase { 
P_CHAR pWord, 

P_SPELL_CASE_CONTEXT pSpellCaseContext 
); 

Call SpellWordSetCase the first time with pWord == pNull tothe context structure. Then pass it the 

words to be(in order) with the same context structure each time. Iteach word in place. To modify 

the default behavior, changeappropriate context parameters (see the definition of 

the_CASE_CONTEXT structure). 

DefaultsminCase: SpellCommonCase unkCase: SpellCommonCase sentence: true 
dictionary: true allCapsWriter: false firstWord: true 
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SpellLineSetCase 

Convert all-upper-case input into a reasonable mix of upper and lower case using dictionary information 
and other lexical clues. 

Returns STATUS. 

mmfmn Frofoiype STATUS EXPORTED SpellLineSetCase ( 

P_CHAR pLine, 

P_SPELL_CASE_CONTEXT pSpellCaseContext 
); 
Identical to SpellWordSetCase, except it expects the input to beline of text, which it splits into tokens as 

required. 

Miscellaneous 

Address of the list of legal dictionaries 



extern const SPELL DICT LIST spellDictList [] 
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SPMGR.H 



This file contains the API for the Spell Manager Class and theSpellManager. 
clsSpellManager inherits firom clsObject. 
theSpellManager is a well-known instance of clsSpellManager. 
Also spell.h, pdict.h 

tifndef SPMGR_INCLUDED 
tdefine SPMGR_INCLUDED 

#ifndef CLSMGR_INCLUDED 
#include <clsmgr.h> 
tendif 

#ifndef WIN_INCLUDED 

#include <win.h> 

tendif 

tifndef XLATE_INCLUDED 

#include <xlate.h> 

tendif 

tifndef GWIN_INCLUDED 

tinclude <gwin.h> 

tendif 

Common typedefs 

This structure is passed to theSpellManager when the user makes thegesture on a window. 

typedef struct SP_MGR_GESTURE { 

GWIN_GESTURE gesture; 
} SP_MGR_GESTURE, * P_SP_MGR_GESTURE; 

Messages 

Sent to Traversal Clients 



msgSpMgrCreateContext 

Piggybacked with nisgTraverseCreate.*Ctx messages. 

Takes VOID, returns STATUS. 

tdefine msgSpMgrCreateContext MakeMsg (clsSpellManager, 1) 

Initiates a spelling traversal. 



msgSpMgrFindMisspelling 

Asks the recipient to find the next misspelled word (using SpellCheck() on successive space-delimited 
tokens). 

Takes SP_MGR_DIALOG, returns STATUS. 

tdefine msgSpMgrFindMisspelling MakeMsg (clsSpellManager, 2) 

Piggybacked with msgTraverseFind. 
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msgSpMgrCorrectMisspelling 

Asks the recipient to correct the misspelled word he previously found in response to a 
msgSpMgrFindMisspelling message. 

Takes SP_MGR_DIALOG, returns STATUS. 

tdefine msgSpMgrCorrectMisspelling MakeMsg(clsSpellManager,3) 

Piggybacked with m^TraverseApply. Correction is in the word field. 

msgSpMgrAcceptMisspelling 

Asks the recipient to accept the misspelled word he previously found in response to a 
msgSpMgrFindMisspelling message. 

Takes SP_MGR_DIALOG, returns STATUS. 

#define msgSpMgrAcceptMisspelling MakeMsg(clsSpellManager,5) 

Piggybacked with msgTraverseApply. Dialog Struct is copied. 

Received From GWin 



msgSpMgrGesture 

This causes theSpellManager to initiate a spell traversal from a gesture, as opposed to from a menu. 

Takes P_SP_MGR_GESTURE, returns STATUS. 

#define msgSpMgrGesture MakeMsg(clsSpellManager,4) 

typedef struct SP_MGR_GESTURE { 

GWIN_GESTURE gesture; 
} SP_MGR_GESTURE, * P_SP_MGR_GESTURE; 

When a user makes the spelling gesture on an embedded window, thesends msgSpMgrGesture to 
theSpellManager with the_MGR_GESTURE structure filled in. 



Miscellaneous 

Quick Help Tags 



tdefine SpMgrReplaceButtonTag MakeTag(clsSpellManager, 1) 

tdefine SpMgrlgnoreButtonTag MakeTag(clsSpellManager,2) 

tdefine SpMgrCancelButtonTag MakeTag(clsSpellManager, 3) 

tdefine SpMgrlnsertionPadTag MakeTag(clsSpellManager, 4) 

tdefine SpMgrTKTableTag MakeTag(clsSpellManager, 5) 

tdefine SpMgrBackgroundTag MakeTag(clsSpellManager, 6) 

tdefine SpMgrClearButtonTag MakeTag(clsSpellManager,7) 

tdefine SpMgrRememberButtonTag MakeTag(clsSpellManager, 8) 

tdefine SpMgrTitleBarTag MakeTag(clsSpellManager, 9) 

tdefine hlpSpMgrReplaceButton SpMgrReplaceButtonTag 

tdefine hlpSpMgrlgnoreButton SpMgrlgnoreButtonTag 

tdefine hlpSpMgrCancelButton SpMgrCancelButtonTag 

tdefine hlpSpMgrlnsertionPad SpMgrlnsertionPadTag 

tdefine hlpSpMgrTKTable SpMgrTKTableTag 

tdefine hlpSpMgrBackground SpMgrBackgroundTag 

tdefine hlpSpMgrClearButton SpMgrClearButtonTag 

tdefine hlpSpMgrRememberButton SpMgrRememberButtonTag 

tdefine hlpSpMgrTitleBar SpMgrTitleBarTag 

// Different help tags for when this is proof instead of spell 

tdefine hlpProoflnsertionPad MakeTag(clsSpellManager,10) 

tdefine hlpProofTKTable MakeTag(clsSpellManager,ll) 
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SR.H 



clsSR inherits from clsObject. 

clsSR is tlie class of theSearchManager. It defines a protocol which clients can respond to implement 
Find and Replace. Clients of this protocol must respond to the "mark" protocol defined in mark.h. 

Debugging Flags 

The Find and Replace mechanism uses the debug flag RIOOOO. 

#ifndef SR_INCLUDED 
#define SR_INCLUDED 1 

#ifndef MARK_INCLUDED 
#include <mark.h> 
#endif 

Common #defines and typedefs 



tdefine srBufSize 



80 



typedef struct 
BOOLEAN 


SR_FLAGS { 
matchCase 






matchWord 




} SR_FLAGS; 


keepOldCase 

findFromEdge 

onBigCard 





// case must match 

// full word search 

// replace with found case 

// search from edge of doc 

// display big card 



typedef struct SR_METRICS { 

CHAR findText [srBufSize] ; 

CHAR replaceText [srBufSize] ; 

MARK_MSG_FLAGS markFlags; 

SR_FLAGS searchFlags ; 

} SR METRICS, * P SR METRICS; 



Statuses 

The current match cannot/may not be replaced. 

#define stsSRCannotReplace MakeStatus (clsSR, 1) 

Messages Sent to Clients via cIsMaric 

msgSRNextChars 

Asks the client to move the token to the next group of characters. 

Takes P_SR_NEXT_CHARS, returns STATUS. 

#define msgSRNextChars MakeMsg(clsSR, 1) 



Argymenfs typedef Struct SR_NEXT_CHARS { 
MARK_MSG_HEADER header; 
U32 maxLen; 

U32 len; 

BOOLEAN blockStart; 
BOOLEAN blockEnd; 
} SR NEXT CHARS, * P SR NEXT CHARS; 



// In: maximum size the group can be 

// Out: the size of the group 

// Out: the group starts a block 

// Out: the group ends a block 
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ComrtseRfs Important: your handler must have the following as its first statement. Replace "clsYourClassHere" with 

the uid of your class. See mark.h. 

MarkHandlerForClass (clsYourClassHere) ; 

This group may be up to maxLen characters in size. The client sets the len parameter to the actual size 
of the group, and if the group is the start and/or end of a block of character, sets the respective flags. A 
block is defined as a logically contiguous group of characters that can be searched. 

Any non-text element usually delimits the end of a block. If the element is an embedded window that 
should be searched, the token should be set to point to the embedded window and stsMarkEnterChild 
(see mark.h) should be returned. If the element is not a child, then it should be simply skipped and the 
token moved to the next group of characters following it. 

Example: If the following text is in the clients data, and msgSRNextChars is received with a maxLen of 
5, the token would should refer to the blocks 1 through 4 in succession. blockStart should be true for 
blocks 1 and 3 and blockEnd should be true for blocks 2 and 4. In this way, "SEN" and "MANTLE" 
can be found, but "GERMAN" which spans some non-text object won't be mistakenly found. 

MESSENGER (non-text-thing) MANTLE 
I II I II 

+ 1 + 2 + + 3 +4+ 

msgSRGetChars 

The component passes back the characters from the location identified by the token. 

Takes P_SR_GET_CHARS, returns STATUS. 

♦define msgSRGetChars MakeMsg(clsSR, 2) 

Arguments typedef struct SR_GET_CHARS { 

MARK_MSG_HEADER header; 

U32 first; // In: character to start with 

U32 len; // In: the number of characters to return 

U32 bufLen; // In: length of the buffer 

P_CHAR pBuf; // In: pointer to the buffer to fill 

} SR_GET_CHARS, * P_SR_GET_CHARS ; 

Comments Important: your handler must have the following as its first statement. Replace "clsYourClassHere" with 

the uid of your class. See mark.h. 

MarkHandlerForClass (clsYourClassHere) ; 

pArgs->first is token-relative and pArgs->len is the number of characters to return. Thus (0,2) requests 
the first two characters, (1,1) requests the second character, and (3,0) requests no characters. 

The string returned must be null-terminated. Note that if len is less than buflLen then this is always 
possible without truncation. Otherwise, the number of characters returned should be one less than 
bufLen and they should still be null terminated. 

msgSRReplaceChars 

Ask the component to replace some of the characters at the location identified by the token. 

Takes P_SR_REPLACE_CHARS, returns STATUS. 

♦define msgSRReplaceChars MakeMsg(clsSR, 3) 

Arguments typedef struct SR_REPLACE_CHARS { 
MARK_MSG_HEADER header; 

S32 first; // In: replacement starts here 

U32 len; // In: ...and is this long 

U32 bufLen; // In: repl. size in characters 

P_CHAR pBuf; // In: the buffer of the characters 
} SR REPLACE CHARS, * P SR REPLACE CHARS; 
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Comments Important: your handler must have the following as its first statement. Replace "clsYourClassHere" with 

the uid of your class. See markh. 

MarkHandlerForClass (clsYourClassHere) ; 

pArgs->first is token-relative, and pArgs->len is the number of characters to replace. Thus (0,2) replaces 
the first two characters, (1,1) replaces the second character, and (3,0) replaces no characters starting 
between the third and fourth (thus effecting an insertion). 

pArgs->first may be negative, indicating replacement of text BEFORE the current token (or large 
indicating AFTER). However, in no case will pArgs->first go beyond the boundaries indicated by the 
blockStart and biockEnd flags from previous calls to msgSRNextChars. 

This message should only affect the token insofar as the replacement makes changes to the data the 
token refers to. For example: if the token refers to the three characters "cat" and the replace messages 
changes the substring "c" (0,1) into "womb", then the token should now refer to the six characters 
"wombat". 

msgSRPositionChars 

Asks the component to reposition the token to some of the characters in the current group. 

Takes P_SR_POSITION_CHARS, returns STATUS. 

#define msgSRPositionChars MakeMsg(clsSR, 4) 

Argwitienfs typedef Struct SR_POSITION_CHARS { 

MARK_MSG_HEADER header; 

S32 first; // In: new position starts here 

U32 len; // In: ...and is this long 

} SR_POSITION_CHARS, * P_SR_POSITION_CHARS; 

Comriietifs Important: your handler must have the following as its first statement. Replace "clsYourClassHere" with 

the uid of your class. See mark.h. 

MarkHandlerForClass (clsYourClassHere) ; 

pArgs->first is token-relative, and pArgs->len is the number of characters to reposition to. Thus (0,2) 
positions to the first two characters, (1,1) positions to the second character, and (3,0) positions to 
between the third and fourth characters. 

pArgs->first may be negative indicating positioning BEFORE the current token (or large indicating 
AFTER). However, in no case will pArgs->first go beyond the boundaries indicated by the blockStart 
and biockEnd flags from previous calls to msgSRNextChars. 



Messages to theSearckManager 



These messages are sent to theSearchManager by PenPoint's standard UI elements. Typical clients do 
not send them. 

msgSRInvokeSearch 

Starts a Find & Replace option sheet. 

Takes P_SR_INVOKE_SEARCH, returns STATUS. 

♦define msgSRInvokeSearch MakeMsg(clsSR, 10) 
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OBJECT 
BOOLEAN 


target; 
fromSelection 
froraGesture 
doFind 




findBackward 




noUI 




useWord 


U16 


useFlags 
reserved; 


GWIN_GESTURE 
SR METRICS 
U32 


gesture; 
metrics; 
reserved2 ; 



typedef struct SR_INVOKE_SEARGH { 

// nil if froraGesture or froraSelection 

1, // start from the selection 

1, // start from the gesture given 

1, // do an initial find 

1, // direction for initial find 

1, // don't open option sheet 

1, // use the word at the gesture or selection 

1; // use the flags in metrics 

// the gesture if froraGesture 

// optional initial text and flags 

} SR_INVOKE_SEARCH, * P_SR_INVOKE_SEARCH ; 

The target of the search is the target argument. However if fromSelection is true then it is the selection; 
or if fromGesture is true then it is from the gesture. 

The user's last saved metrics are always used except that 

♦ metrics.findText is used if it is not the empty string 

♦ metrics. replaccText is used if it is not the empty string 

♦ metrics. markFlags & metrics.searchFlags are used if pArgs->useFlags is true 

If doFind is true, then an initial find is executed. 

If noUI is true, then the option sheet isn't created. This is only useful in conjunction with doFind 
(otherwise, nothing has happened!), the result being a "find next" operation. 

If useWord is true, then the find text will be fetched from the target with msgSRGetChars. 



msgSRRememberMetrics 

Asks theSearchManager to remember the current settings of a Find & Replace option sheet 

Takes P_SR_METRICS, returns STATUS. 

Idefine rasgSRRemeraberMetrics MakeMsg(clsSR, 12) 

typedef struct SR_METRICS { 

CHAR findText [srBufSize] ; 

CHAR replaceText [srBuf Size] ; 

MARK_MSG_FLAGS raarkFlags; 

SR_FLAGS searchFlags ; 

} SR_METRICS, * P_SR_METRICS; 

As a result, when theSearchManager option sheet next appears it will have the these settings. 
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STROBJ.H 



This file contains the API definition for clsString. 

clsString inherits firom clsByteBuf. 

clsString provides a facility to store null-terminated ASCII byte strings. Each object of clsString stores a 
single string. This class provides convenient object filing of the string data. Storage for each object's 
string is allocated out of the creator's shared process heap using OSHeapBlockAlloc. 

Clients who want to store uninterpreted byte arrays should use clsByteBuf (see bytebuf h). 

clsString and clsByteBuf do not share messages. clsByteBuf messages cannot be sent to a clsString 
object. 

#ifndef STROBJ_INCLUDED 
tdefine STROBJ_INCLUDED 

#include <go.h> 
tinclude <clsmgr.h> 

typedef OBJECT STROBJECT, *P STROBJECT; 



Class Messages 



iraomenfs 



comments 



msgNew 

Creates a new string object. 

Takes P_STROBJ_NEW_ONLY, returns STATUS. Category: class message. 

typedef struct STROBJ_NEW_ONLY { 

P_CHAR pString; 
} STROBJ_NEW_ONLY, *P_STROBJ_NEW_ONLY; 

#define strObjNewFields \ 

objectNewFields \ 

STROB J_NEW_ONLY st rob j ; 

typedef struct STROBJ_NEW { 

StrObjNewFields 
} STROBJ_NEW, *P_STROBJ_NEW; 

This message allocates shared heap storage for the specified string and copies the client string data into 
it. 



Argyioients 



msgNewDefaults 

Initializes the STROBJ_NEW structure to default values. 

Takes P_STROBJ_NEW, returns STATUS. Category: class message. 

typedef struct STROBJ_NEW { 

StrObjNewFields 
} STROBJ NEW, *P STROBJ NEW; 



Sets 



pNew->strobj.pString = pNull; 
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Object Messages 



iriients 



msgStrObjGetStr 

Passes back the object's string. 

Takes PP_CHAR, returns STATUS. 

tdefine msgStrObjGetStr MakeMsg(clsString, 1) 

The pointer passed back references the object's global storage. Clients must not modify or free this 
storage. 



msgStrObjSetStr 

Copies the specified string data into the object's string buffer. 

Takes P_CHAR, returns STATUS. 

#define msgStrObjSetStr MakeMsg(clsString, 2) 

imerrts Previously retrieved string pointers will be invalid after this operation. Clients must call 

msgStrObjGetStr to retrieve a pointer to the valid object buffer. 

Observer Messages 

msgStrObjChanged 

Sent to observers when the string object data changes. 
Takes OBJECT, returns nothing. Category: observer notification. 
#define msgStrObjChanged MakeMsg(clsString, 3) 

ifiients The message argument is the UID of the clsString object that changed. 



PI 11 F 1 NT A PI H E F E R IN CE / VOL II 
PART 9 / UTILITY CiASSES 



TS.H 



This file contains the API definition for clsTable. 

clsTable inherits firom clsObject. 

clsTable provides a general-purpose table mechanism with random and sequential access. The table 
allows clients to create, destroy, modify, and access the table and its data using a row and column 
metaphor. Data for the table is stored in a table file, whose lifetime can be independent to that of the 
table object. 

Tables are two dimensional arrays consisting of a fixed number of columns and a variable number of 
rows. Each column can contain data of a single data type such as a U32, a variable length string, a fixed 
sized byte field, date and time, etc. 

The number of and types of these columns are defined when the table is created. Once that table has 
been created, these parameters cannot be changed. 

Clients access rows in the table using a TBL_ROW_POS data structure. The value for this row position is 
returned to the client when a row is added to the table. All messages for manipulating data in the table 
require this value to specify an individual row. 

Clients address columns using their position in the TBL_COL_DESC array which the client provides in 
the TBL_CREATE data structure during msgNew. 

The table is an observable object and clients choosing to be observers will receive notification when data 
in the table changes or a row has been added to or removed from the table. 

tifndef TS_INCLUDED 
tdefine TS_INCLUDED 

#include <clsmgr.h> 
#include <fs.h> 
tinclude <resfile.h> 



Status Codes 



Status values return by messages to clsTable. 

tdefine stsTBLRefCountNotZero 
♦define stsTBLColNameNotFound 
tdefine stsTBLStrBufTooSmall 
tdefine stsTBLBadNewFlags 
tdefine stsTBLEndOf Table 
tdefine stsTBLInvalidSortColValue 
tdefine stsTBLCorruptedlndex 
tdefine stsTBLColNotlndexed 
tdefine stsTBLContainsIndexedCols 



MakeStatus ( 


ClsTable, 


1 ) 


MakeStatus ( 


ClsTable, 


2 ) 


MakeStatus ( 


ClsTable, 


3 ) 


MakeStatus ( 


ClsTable, 


4 ) 


MakeStatus { 


clsTable, 


5 ) 


MakeStatus ( 


ClsTable, 


7 ) 


MakeStatus ( 


ClsTable, 


8 ) 


MakeStatus ( 


clsTable, 


9 ) 


MakeStatus { 


clsTable, 


10 ) 
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Cominoii macros and typedefs 

♦ Class Declaration 



#define clsTable 

♦ Object Declarations 

typedef OBJECT TABLE; 
typedef OBJECT TBLOBJ; 
typedef TBLOBJ *P_TBLOBJ; 

♦ Table Parameter Definitions 

tdefine TBL_MAXCOLNAMELEN 
fdefine TBL_MAXTBLNAMELEN 
fdefine TBL_MAXROWCOUNT 

♦ Table Row Definitions 
typedef RES_ID TBL_ROW_POS, 



MakeWKN(2003, 1, wknGlobal) 



nameBufLength 
nameBufLength 
0x2000 



// 8192 entries 



typedef U16 
typedef U16 
typedef U16 
typedef S32 
typedef SI 6 



TBL_ROW_NUM, 
TBL_ROW_COUNT, 
TBL_ROW_LENGTH, 
TBL_ROW_OFFSET, 
TBL REF COUNT, 



♦ Table Data Type Definitions 

typedef P_U8 
typedef P_UNKNOWN 

♦ Column Index Declarations 

typedef U16 TBL_COL_INX_TYPE, 
typedef U16 TBL_COL_COUNT, 
typedef U16 TBL_COL_LENGTH, 
typedef U32 TBL_COL_OFFSET, 

♦ Column Descriptor Definitions 



*P_TBL_ROW_POS; 
*P_TBL_ROW_NUM; 
*P_TBL_ROW_COUNT; 
*P_TBL_ROW_LENGTH ; 
*P_TBL_ROW_OFFSET ; 
*P TBL REF COUNT; 



P_ROW_BUFFER, *PP_ROW_BUFFER; 
P TBL COL DATA HOLDER; 



*P_TBL_COL_INX_TYPE ; 
*P_TBL_COL_COUNT; 
*P_TBL_COL_LENGTH ; 
*P TBL COL OFFSET; 



// Absolute TS Row Key 

// Position relative TS Row Key 



typedef enum TBL_TyPES { 
tsChar = 0, 
tsCaseChar = 1, 
tsU16 = 2, 
tsU32 = 3, 
tsFP = 4, 

tsDate = 5, 
tsString = 6, 
tsCaseString = 7, 
tsByteArray = 8, 
tsUUID = 9, 
tsLastType = tsUUID 

} TBL_TYPES; 

typedef struct TBL COL DESC { 



// fixed length byte array of case sensitive chars 

// fixed length byte array of case insensitive chars 

// unsigned 16 bit integer 

// unsigned 32 bit integer 

// double precision floating point 

// date field (system compressed time format) 

// null-terminated variable length ascii string (case sensitive) 

// same as tsString but is case insensitive 

// variable length byte array, contained in unsigned chars 

// UUID struct. 



CHAR 

TBL_TyPES 

TBL_COL_LENGTH 

TBL_COL_INX_TYPE 

TBL_COL_OFFSET 

BOOLEAN 



name[TBL_MAXCOLNAMELEN] ; 

type; 

length; 

repeatFactor; 

offset; 

sorted; 



// Column name 

// Column type 

// Column data length 

// # of times to repeat the column 

// Column offset in the row 

// Is the column sorted? 



} TBL_COL_DESC, *P_TBL_COL_DESC; 

♦ Variable Length Data Buffer Definition 



typedef struct TBL_STRING { 
U16 strLen; // In/Out; 
U16 strMax; // In: 
P_CHAR pStr; //In: 

} TBL STRING, *P TBL STRING; 



length of string or byte array column data 
length of string or byte array buffer 
pointer to client buffer. 
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Class Messages 



msgNew 

Creates a new table object. 

Takes P_TBL_NEW, returns STATUS. Category: class message. 

Arguments typedef enum TBL_FREE_BEHAVE { ^ 

tsFreeNoDeleteFile =0, // Free only the object, not the file m 

tsFreeDeleteFile = flagO, // Destroy the file when freed < 

tsFreeWhenNoClients = flagl, // Free when # clients accessing is " 

tsFreeNoObservers = flag2, // Free when # of observers is t 

tsFreeNoCompact = flag3, // Don't compact the table when freed p 

tsFreeDefault = tsFreeNoDeleteFile ^ 

} TBL_FREE_BEHAVE, *P_TBL_FREE_BEHAVE; 0> 

typedef enum TBL_EXIST { ■" 

// Same values as FS_EXIST_MODE 

tsExistOpen =0, // Open an existing table 

tsExistGenError =1, // Return error if table exists 

tsExistGenUnique =2, // Create table with a unique name 

tsNoExistCreate = MakeUl6(0, 0) , // Create a new table 

tsNoExistGenError = MakeU16(0, 1) , // Return error if no table exists 

tsExistDefault = tsExistOpen | tsNoExistCreate 

} TBL_EXIST, *P_TBL_EXIST; 

typedef struct TBL_CREATE { 

TBL_COL_COUNT colCount; // number of columns 

P_TBL_COL_DESC colDescAry; // TBL_COL_DESC array 
} TBL_CREATE, *P_TBL_CREATE; 

typedef struct TBL_NEW_ONLY { 

CHAR name [TBL_MAXTBLNAMELEN] ; // Table name 

FS_LOCATOR locator; // Table file 

TBL_EXIST exist; // Table exist behavior 

TBL_CREATE create; // Column specifications 

TBL_FREE_BEHAVE freeBehavior; // Table free behavior 

BOOLEAN createSemaphore; // Provide semaphore? 

} TBL_NEW_ONLY, *P_TBL_NEW_ONLY ; 

tdefine tableNewFields \ 
objectNewFields \ 
TBL_NEW_ONLY table; 

typedef struct TBL_NEW { 

tableNewFields 
} TBL_NEW, *P_TBL_NEW; 

Corattiertfs This message creates a new table file or opens an existing file. 

The table name is an optional field. The locator and colDescAry fields must be valid and colCount 
must be non zero or this message returns stsBadParam. 

Retiir« ¥aiye stsTBLBadNewFlags TBL_EXIST flags were invalid. 

StsBadParam locator or colDescAiy fields are invalid. colCount is 0. 

msgNewDefaults 

Initializes the TBL_NEW structure to default values. 

Takes P_TBL_NEW, returns STATUS. Category: class message. 

typedef struct TBL_NEW { 

tableNewFields 
} TBL NEW, *P TBL NEW; 
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iinetits Zeroes out pNew->table and sets: 

pNew->table.name[0] = '\0'; 

pNew->t able. locator. uid = objNull; 

pNew->t able. locator. pPath = pNull; 

pNew->t able. exist = tsExistDefault; 

pNew->table . create . colCount = 0; 

pNew->table.create.colDescAry = pNull; 

pNew->table . f reeBehavior = tsFreeDefault; 

pNew->table . createSemaphore = false; 

msgDestroy 

Destroys an existing table object. 

Takes OBJ_KEY, returns STATUS. Category: class message. 

irnents This message destroys the table object and frees the table files if the object was created with the 

tsFreeDeleteFile flag specified. 

The table file will not be destroyed regardless of whether tsFreeDeleteFile was specified if there are still 
accessors to the table. Only the object will be freed. 

rn ¥oiije stsTBLRefCountNotZero The number of accessors of the table is not zero. The table file will not be 

destroyed. 

Object Messages 

Table Rov^ Addition and Deletion Messages 

msgTBLAddRow 

Adds a row/record with no data to the table server object. 

Takes P_TBL_ROW_POS, returns STATUS. 

#define msgTBLAddRow MakeMsg(clsTable, 1) 

riieritii The TOW position (TBL_ROW_POS) for the new row is passed back. The row position is the key to access 

data in the row or to delete the row. 

msgTBLDeleteRow 

Deletes the specified row. 

Takes P_TBL_ROW_POS, returns STATUS. 

tdefine msgTBLDeleteRow MalceMsg(clsTable, 5) 

mients Rows are deleted from the table at the completion of this call. The row's TBL_ROW_POS is no longer 

valid afi:er the row has been deleted. 

« n ¥cil«e stsTBLEndOffable TBL ROW POS value was not found in the table. 
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Table Data Messages 



msgTBLColGetData 

Passes back the data for the specified row and column. 

Takes P_TBL_COL_GET_SET_DATA, returns STATUS. 

#define msgTBLColGetData MakeMsgCclsTable, 13) 

Arguments typedef Struct TBL_COL_GET_SET_DATA { JJ> 

TBL_ROW_POS tblRowPos; // In: Table row position *5 

TBL_COL_INX_TYPE colNuinber; // In: Column number " 

P_TBL_COL_DATA_HOLDER tblColData; // Out: Column data t 

} TBL COL GET SET DATA, *P TBL COL GET SET DATA; P 

--------- 3 

Comments tblColData is of type P_TBL_STRING if the column type is tsString, tsCaseString, or tsByteArray. o- 

The client is responsible for allocating storage for the tblStr.pStr buffer. If the buffer is too small to 
accomodate the requested data, the table will return stsTBLStrBufrooSmall and pass back the 
truncated data and the actual length of the data in tblStr.strLen. 

Retorn Voiue stsTBLStrBufTooSmall Returned if column type is tsString, tsCaseString or tsByteArray and 

tblStr.strMax is less than the actual data length. The data is truncated and the length is returned in 
tblStr.strLen. 

stsTBLEndOffable TBL ROW POS value was not found in the table. 



msgTBLColSetData 

Sets the data for the specified row and column. 

Takes P_TBL_COL_GET_SET_DATA, returns STATUS. 

#define msgTBLColSetData MakeMsg(clsTable, 14) 

Messoge typedef struct TBL_COL_GET_SET_DATA { 

Arguments TBL_ROW_POS tblRowPos; // In: Table row position 

TBL_COL_INX_TYPE colNumber; // In: Column number 

P_TBL_COL_DATA_HOLDER tblColData; // Out: Column data 

} TBL_COL_GET_SET_DATA, *P_TBL_COL_GET_SET_DATA; 

Comments tblColData is of type P_TBL_STRING if the column type is tsString, tsCaseString, or tsByteArray. 

Clients are responsible for setting the strLen field of the TBL_STRING argument for all column types. 

ietorn ¥olwe stsTBLEndOfTablc TBL ROW POS value was not found in the table. 



msgTBLRowGetData 

Gets the contents of an entire row. 

Takes P_TBL_GET_SET_ROW, returns STATUS. 

#define msgTBLRowGetData MakeMsg(clsTable, 15) 

Arguments typedef struct TBL_GET_SET_ROW { 

TBL_ROW_POS tblRowPos; //In: Which row 

P_UNKNOWN pRowData; // Out: Row data 

} TBL_GET_SET_ROW, *P_TBL_GET_SET_ROW; 

Comments Not valid for tables containing variable length columns. 

The client is responsible for providing storage for the pRowData buffer. The length of a table row can 
be obtained using msgTBLGetRowLength. 
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ieturrs ¥«lue stsTBLEndOfTablc TBL_ROW_POS value was not found in die table. 

stsTBLContainsIndexedCols Table contains variable length columns. 

Ses? M'ia msgTBLGetRowLength 



msgTBLRowSetData 

Sets the contents of an entire row. 

Takes P_TBL_GET_SET_ROW, returns STATUS. 

tdefine msgTBLRowSetData MakeMsg(clsTable, 16) 

essage typedef struct TBL_GET_SET_ROW { 

rgiimerjfs TBL_ROW_POS tblRowPos; // In: Which row 

P_UNKNOWN pRowData; // Out: Row data 

} TBL_GET_SET_ROW, *P_TBL_GET_SET_ROW; 

smments Not valid for tables containing variable length columns. 

sturn ¥ai«e stsTBLEndOfTablc TBL_ROW_POS value was not found in the table. 

StsTBLContainsIndexedCols Table contains variable length columns. 

je Mso msgTBLGetRowLength 

r Table Information Messages 



msgTBLGetlnfo 

Gets the table header information. 

Takes P_TBL_HEADER, returns STATUS. 

♦define msgTBLGetlnfo MakeMsg(clsTable, 10) 

typedef struct TBL_HEADER { 

TBL_COL_COUNT colCount; // number of columns in table 
CHAR name[TBL_MAXTBLNAMELEN],7/ non-file table reference 

TBL_ROW_COUNT nRows; // how many rows in table 

TBL_ROW_LENGTH rowLength; // row buffer length 

TBL_ROW_POS firstRow; // position of first row in table 

TBL_ROW_POS currentRow; // position of current row in table 

TBL_ROW_POS lastRow; // position of last row in table 

TBL_REF_COUNT refCount; // number of active clients. 

} TBL_HEADER, *P_TBL_HEADER, **PP_TBL_HEADER; 

msgTBLGetColCount, , , 



msgTBLGetColCount 

Gets the number of columns in the table. 

Takes P_TBL_COL_COUNT, returns STATUS. 

♦define msgTBLGetColCount MakeMsg(clsTable, 7) 



msgTBLGetColDesc 

Passes back the column description for the specified column. 

Takes P_TBL_GET_COL_DESC, returns STATUS. 

♦define msgTBLGetColDesc MakeMsg(clsTable, 2) 
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Argumenfs typedef Struct TBL_GET_COL_DESC { 

TBL_COL_INX_TYPE colinx; // In: column number 

TBL_COL_DESC colDesc; // Out: column decription 

) TBL_GET_COL_DESC, *P_TBL_GET_COL_DESC; 

msgTBLGetRowCount 

Gets the current number of rows in the table. 

Takes P_TBL_ROW_COUNT, returns STATUS. J2 

♦define msgTBLGetRowCount MakeMsg(clsTable, 6) <5 

>■ 

msgTBLGetRowLength 

Gets the length (in bytes) of the specified row. 

Takes P_TBL_ROW_LENGTH, returns STATUS. 

#define msgTBLGetRowLength MakeMsg(clsTable, 8) 

Comttienfs The row length indicates the total width of all columns for each row in the table. This information is 

useful when getting and setting row data. 

See Also msgTBLRowGetData 



msgTBLGetState 

Gets the current state of a specified row. 

Takes P_TBL_GET_STATE, returns STATUS. 

tdefine msgTBLGetState Mak:eMsg(clsTable, 11) 

Argytments typedef enum TBL_STATE { 

tsBegin =0, // rowPos is the first row 

tsEnd =1, // rowPos is the last row 

tsPosition =2 // rowPos is not first or last 
} TBL_STATE, *P_TBL_STATE; 

typedef struct TBL_GET_STATE { 

TBL_STATE tblState; // Out: State of the specified row 
TBL_ROW_POS tblRowPos; // In: Row position of the specified row. 

} TBL_GET_STATE, *P_TBL_GET_STATE; 

Comments The State of a row in the table indicates its general positioning within the table. 

Return Value stsTBLEndOfTablc TBL ROW POS value was not found in the table. 



Table Access Messages 



msgTBLBeginAccess 

Initiates table access by a client on this table. 

Takes P_TBL_BEGIN_ACCESS, returns STATUS. 

tdefine msgTBLBeginAccess MakeMsg{clsTable, 17) 

AfQum^nts typedef struct TBL_BEGIN_ACCESS { 

OBJECT sender; // In: sender's id IFF wants to be observer 

TBL_ROW_LENGTH rowLength; // Out: Length of the first row 
} TBL_BEGIN_ACCESS, *P_TBL_BEGIN_ACCESS; 

Comments Passes back the row length of the first row. Adds the sender to the table's observer list. 
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msgTBLEndAccess 

Ends client access to the table. 

Takes P_TBL_END_ACCESS, returns STATUS. 

#define msgTBLEndAccess MakeMsg(clsTable, 18) 

iimenfs typedef struct TBL_END_ACCESS { 

OBJECT sender; //In: Sender's uid 
} TBL_END_ACCESS, *P_TBL_END_ACCESS; 

Removes sender from the observer list. 

msgTBLSemaClear 

Releases the table s semaphore. 
Takes nothing, returns STATUS. 

#define msgTBLSemaClear MakeMsg{clsTable, 23) 

irrierits The next client currently waiting on the table semaphore will unblock when this messages completes. 



msgTBLSemaRequest 

Requests access to the table's semaphore. 

Takes nothing, returns STATUS. 

tdefine msgTBLSemaRequest MakeMsg(clsTable, 22) 

Waits on the table semaphore if another client already has access. Provides exclusive access of the table 
semaphore to the sender when it returns. 

Semaphore access has no timeout. 



Table Search Messages 



msgTBLFindFirst 

Finds the first record that meets the search specification. 

Takes P_TBL_FIND_ROW, returns STATUS;. 

#define msgTBLFindFirst Mak;eMsg(clsTable, 3) 

typedef enum TBL_BOOL_OP { 

tsEql =0, // Match if operands are equal 

tsEqual =1, // Match if operands are equal 

tsLess =2, // Match if opndl < opnd2 

tsGreater = 3, // Match if opndl > opnd2 

tsGreaterEqual =4, // Match if opndl <= opnd2 

tsLessEqual =5, // Match if opndl >= opnd2 

tsNotEqual = 6, // Match if the operands do not match 

tsSubstring =7, // Match if opndl is an exact substring of opnd2 

tsStartsWith =8, // Match if opndl starts with opnd2 

tsAlwaysTrue =9 // Match the first (or next) row 

} TBL_BOOL_OP, *P_TBL_BOOL_OP; 

typedef struct TBL_SEARCH_SPEC { 

TBL_COL_INX_TYPE colOperand; // In: Which column 

TBL_BOOL_OP relOp; // In: Operation 

P_TBL_COL_DATA_HOLDER pConstOperand; // In: Value to search against 

} TBL SEARCH SPEC, *P TBL SEARCH SPEC; 



(/) 
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typedef struct TBL_FIND_ROW { 

TBL_ROW_POS rowPos; // In: Out - current table position 

TBL_ROW_NUM rowNum; // Out: indexed column row number 

TBL_SEARCH_SPEC srchSpec; // In: search query 

TBL_COL_INX_TYPE sortCol; // In: which column sort to use (if any) 

P_ROW_BUFFER pRowBuffer; // In: pointer to client's buffer space 

} TBL_FIND_ROW, *P_TBL_FIND_ROW; 

Comments Passes back the TBL_ROW_POS and TBL_ROW_NUM of the row. 

srchSpec.pConstOperand is of type P_TBL_STRING if the column type is tsString, tsCaseString, or 
tsByteArray. The length of the string/array used in the search is decalred in the strLen field of the < 

TBL_STRING struct. Clients are responsible for setting this field to the appropriate length for columns of 
type tsString, tsCaseString, and tsByteArray. 

srchSpec.pConstOperand is ignored if srchSpec.relOp is tsAlwaysTrue. 

Currently, tsSubstring searches are always case sensitive regardless of the column type. 

lietyrn Valye stsTBLEndOfTable No data was found matching the search spec. 

stsTBLInvalidSortColValue sortCol is not a valid column value. 

msgTBLFindNext 

Find the next record following the specified TBL_RO"W_POS that meets the search specification. 

Takes P_TBL_FIND_ROW, returns STATUS. 

#define msgTBLFindNext MakeMsg{clsTable, 4) 

Message typedef struct TBL_FIND_ROW { 

Argy?Tieiits TBL_ROW_POS rowPos; // In: Out - current table position 

TBL_ROW_NUM rowNum; // Out: indexed column row number 

TBL_SEARCH_SPEC srchSpec; // In: search query 

TBL_COL_INX_TYPE sortCol; // In: which column sort to use (if any) 

P_ROW_BUFFER pRowBuffer; // In: pointer to client's buffer space 

} TBL_FIND_ROW, *P_TBL_FIND_ROW; 

Commerrts Passes back the TBL_ROW_POS and TBL_ROW_NUM of the row. 

srchSpec.pConstOperand is of type P_TBL_STRING if the column type is tsString, tsCaseString, or 
tsByteArray. The length of the string/array used in the search is decalred in the strLen field of the 
TBL_STRING struct. Clients are responsible for setting this field to the appropriate length for columns of 
type tsString, tsCaseString, and tsByteArray. 

srchSpec.pConstOperand is ignored if srchSpec.relOp is tsAlwaysTrue. 

If srchSpec.colOperand is an unsorted column, then the order of the rows searched is random. 

Return V'slyt^ StsTBLEndOfTable No data was found matching the search spec, or rowPos is was not found in the 

table. 

StsTBLInvalidSortColValue sortCol is not a valid column value. 

\r Table Utility Messages 

msgTBLFindColNum 

Passes back the column number for the specifed column name. 

Takes P_TBL_COL_NUM_FIND, returns STATUS. 

tdefine msgTBLFindColNum MakeMsg(clsTable, 12) 
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Irgomenfs typedef Struct TBL_COL_NUM_FIND { 

P_CHAR name; // In: Column name 

TBL_COL_INX_TYPE number; // Out: Column number 

} TBL_COL_NUM_FIND, *P_TBL_COL_NUM_FIND; 

leium ¥fiioe stsTBLColNameNotFound A column with the specified name does not exist. 



msgTBLCompact 

Compacts the table without closing it. 

Takes nothing, returns STATUS. 

tdefine msgTBLCompact MakeMsg(clsTable, 24) 

This message allows clients to compact a table on demand. Compaction frees up any storage associated 
with previously deleted rows and compacts the table to its minimum file size. Ordinarily, a table is 
compacted automatically when the last client accessing the table closes it unless specifically prevented by 
specifying tsFreeNoCompact during msgNew. 

msgTBLRowNumToRowPos 

Converts a TBL_ROW_NUM to its corresponding TBL_ROW_POS for the specified column. 

Takes P_TBL_CONVERT_ROW_NUM, returns STATUS. 

tdefine msgTBLRowNumToRowPos MakeMsg(clsTable, 28) 

Argomenfs typedef Struct TBL_CONVERT_ROW_NUM { 

TBL_ROW_POS rowPos; // Out: - Table row pos. 

TBL_ROW_NUM rowNum; //In: - Index row number. 

TBL_COL_INX_TYPE colNum; //In: - Indexed (sorted) column number. 

} TBL_CONVERT_ROW_NUM, *P_TBL_CONVERT_ROW_NUM; 

Comments This message is defined only for sorted columns. Unsorted columns do not have a defined order. 

ieturn Value stsTBLEndOfTable rowNum is larger than the number of rows in the table. 

stsTBLColNotlndexed The specified column is not sorted. 



Observer Messages 



msgTBLRowAdded 

Sent to observers indicating that a row has been added. 

Takes P_TBL_ROW_POS, returns STATUS. Category: observer notification. 

#define msgTBLRowAdded MakeMsg(clsTable, 19) 

A pointer to the newly added TBL_ROW_POS is sent as an argument. 

msgTBLRowDeleted 

Sent to observers indicating that a row has been deleted. 
Takes nothing, returns STATUS. Category: observer notification. 
♦define msgTBLRowDeleted MakeMsg(clsTable, 20) 
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Observer Messages 



msgTBLRowChanged 

Sent to observers indicating that row data has been changed. 
Takes P_TBL_ROW_POS, returns STATUS. Category: observer notification, 
tdefine msgTBLRowChanged MakeMsg(clsTable, 21) 

Comments A pointer to the changed TBL_ROW_POS is sent as an argument. 
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UNDO.H 



This file contains the API definition for theUndoManager. theUndoManager is the wknProcessGlobal 
instance of clsUndo, 

clsUndo inherits from clsList. 

The functions described in this file are contained in MISC.LIB. 



Introduction 

theUndoManager provides a centralized facility for managing undo information. dieUndoManager 
supports undo of user interface actions. 

An undoable operation, or "undo transaction," is a collection of "undo items." Typically an undoable 
operation is a small UI action (e.g. deleting some text). 

When the user issues an "Undo" command the most recent undo transaction will be undone. A typical 
scenario goes something like this: 

♦ In response to some user interface action, a message handler begins an undo transaction with 
msgUndoBegin and then sends messages which manipulate the application's data. 

♦ As the data manipulation routines do their work, they add undo items to the undo transaction via 
msgUndoAddltem. 

♦ When the user interface handler regains control, the transaction is closed with msgUndoEnd. 

♦ At some later date, the transaction might be undone. theUndoManager undoes a transaction by 
sending msgUndoItem to each item in the transaction (in the reverse order in which they were 
added). 

♦ If the transaction is not undone, but instead falls off the end of the undo transaction queue, then 
the transaction is freed. (A transaction is also freed if the application is terminated.) 
theUndoManager frees a transaction by sending msgUndoFreeltemData to each item in the 
transaction. (But see the comments near the typedef UNDO_ITEM for some circumstances under 
which theUndoManager doesn't send msgUndoFreeltemData but instead frees the item itself.) 

Common Messages 

Typical application code will send the following messages to theUndoManager: 

♦ msgUndoBegin 

♦ msgUndoEnd 

♦ msgUndoAddltem 

Typical application code will receive the following messages from theUndoManager: 

♦ msgUndoItem 

♦ msgUndoFreeltemData 

See the individual descriptions of each of these messages for more information. 
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Debugging Flags 

Undo's debugging flag set is 'U.' Defined flags are: 

0001 Show messages sent to theUndoManager. 

0002 Show clsUndo initiaHzation. 
0004 Show msgUndoAddltem. 

0008 Show undoing a undo transaction. 
0010 Show creating a undo transaction. 
0020 Show destroying an undo transaction. 

The Current Transaction 

At any time, there is at most one current undo transaction open. The current undo transaction includes: 

♦ a unique id of type UNDO_ID 

♦ the OS_TASK_ID of the task that issued the msgUndoBegin that began the transaction 

♦ a nesting count which is the number of msgUndoBegin's minus the number of misgUndoEnd's. 
(See the section "Nesting of msgUndoBegin and msgUndoEnd.") 

♦ a heap with local scope from which clients can allocate space for undo information 

♦ a list of undo items added to the transaction so far.. 

The Undo Queue 

theUndoManager maintains a queue of undo transactions. By default theUndoManager has a queue 
length of 2, but an application can set the limit by sending msgUndoLimit to theUndoManager. 

Your code should not depend on any particular queue size. 

Nesting of msgUndoBegin and msgUndoEnd 

In response to msgUndoBegin, theUndoManager opens a new transaction if there is no open 
transaction; otherwise it simply increments a "nesting count." The nesting count is decremented when 
theUndoManager receives msgUndoEnd. When the count becomes zero, the transaction is closed. 

This allows you to write code that doesn't know whether it there is an open transaction or not. If the 
code wants to record undo information, it can simply send a msgUndoBegin / msgUndoEnd pair. If 
there was no open transaction, the result is that one will be created. And if there is one open, then the 
code's items will be added to that one. 

It is vital that every msgUndoBegin have a matching msgUndoEnd! 

To guard against erroneous code never terminating the current transaction, and thus having that 
transaction slowly consume all of system memory, there is a bounds on the depth of nesting permitted. 
(This bounds is approximately 1000.) If the bounds is exceeded, the open transaction is automatically 
closed. 
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Memory Management 

Each undo item records the information necessary to undo and/or free itself. 

Often this information has to be remembered in allocated memory or objects that must be freed once 
the item can no longer be undone. For instance, an undoable operation might involve deleting an 
object. However, you probably don't want to destroy the object until you're sure that the operation can't 
be undone. But eventually that object has to be destroyed. 

Normally theUndoManager will send msgUndoFreeltemData to the object stored in each UNDOJTEM. 

The handler should respond by freeing any resources associated with the item. Typically those resources ^ 

are pointed to by item.pData. 

But there are five ways in which you and theUndoManager can cooperate so that theUndoManager can 
free the resources for you. 

♦ If ufDatalsHeapNode is set in item.flags, then item.pData must point to a heap block. 
theUndoManager will free item.pData by calling OSHeapBlockFree(item.pData). 

♦ If ufDatalnUndoHeap is set in item.flags, then item.pData must point to heap block allocated 
from the current transaction's heap. theUndoManager will free item.pdata when it destroys the 
transactions's heap. 

♦ If ufDatalsObject is set in item.flags, then item.pData must be an object UID. theUndoManager 
will free item.pdata by calling ObjectSend(msgDestroy, item.pData, ...). (See the section "Freeing 
Undone Items" for one reason NOT to use this variation.) 

♦ If ufDatalsSimpie is set in item.flags, then item.pData is treated as a 32 bit value. There is no need 
for theUndoManager to do anything to free item.pData. 

♦ If none of the above flags is set in item.flags, and item.dataSize is non-zero, then when the item is 
added to the transaction (with msgUndoAddltem) theUndoManager copies item.dataSize bytes 
from item.pData into a block allocated from the current transaction's heap. theUndoManager then 
frees item.pData when it destroys the transactions's heap. 

Freeing Undone Items 

Even an item that has been undone will be freed. It might be automatically freed by theUndoManager, 
as described in the section on Memory Management, or it might be freed by sending 
msgUndoFreeltemData to item.object. 

Often freeing an item's data is done the same way regardless of whether the item has been undone or 
not. But there are cases where the difference is very important. Here's an example. Assume that the 
undoable operation includes deleting an object. If the operation is undone, then the object is "put back" 
into the application. 

If the item IS undone, then the object should NOT be destroyed when the item is freed. But if the 
operation IS NOT undone, then the object should be destroyed when the object is destroyed. 

For items that need to free the item's data differently in these two cases, the fact that the item has been 
undone should be recorded in the item when msgUndoItem is received. Then the code responding to 
msgUndoFreeltemData can check this recorded value. (One convenient place to record this value is in 
the item's ufClient flags.) 
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Adding Items When No Transaction is Open 

When theUndoManager is undoing a transaction, there is no current open transaction. But, as 
described in the typical scenario above, data manipulation routines will attempt to add items anyhow. 
Therefore it is CRITICAL that your code check the value returned from msgUndoAddltem and handle 
it property'. 

There are several ways to do this, but here's one convenient approach. (This approach works ONLY if 
you DON'T use any of theUndoManager's memory management functionality.) 

If you're not using the memory management facilities of theUndoManager, then you're most likely 
allocating memory to hold the client data part of an undo item. That memory has been allocated before 
calling msgUndoAddltem and must be freed if the msgUndoAddltem fails. Conveniently, an item's 
client data can be freed by sending msgUndoFreeltemData to the object stored in item.object. 

Simply define a utility routine that attempts to add an item, and which frees the item if adding fails. 
Then always use that routine to add items. The routine will look something like: 

if (Ob jectCall (msgUndoAddltem, theUndoManager, pitem) < stsOK) { 
return Ob jCallWarn (msgUndoFreeltemData, pItem->object, pItem) ; 

} else { 

return stsOK; 

} 

Subclass Issues 

A class and any number of its ancestors may contribute items to an undo transaction. 

Thus, every msgUndoFreeltemData handler should first check that item.subclass is the expected value. 
If it isn't, the message should be passed onto the ancestor. So a msgUndoFreeltemData handler should 
look something like: 

MsgHandlerWithTypes(RTItemUndoFreeItemData, P_UNDO_ITEM, PP_DATA) 
( 

if (pArgs->subclass != clsRTItem) { 
return ObjectCallAncestorCtx(ctx) ; 

} else { 

} 



Flushing the Undo Queue 

There may be "points of no return" in an application's execution beyond which undoing previous 
operations is impossible or non-sensical. (For instance, it may not be possible to undo operations if the 
application's data files are saved via msgAppSave.) 

You should flush the queue when one of these "points of no return" is encountered. The queue can be 
flushed by performing the following three steps: (1) get the current undo limit via msgUndoGetMetrics, 
(2) send msgUndoLimit with a pArgs of (which actually flushes the queue), and (3) send 
msgUndoLimit, but this time with the limited returned by the previous call to msgUndoGetMetrics. 
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^ Aborting a Transaction 



Sometimes it is necessary to abort an operation part way through. (For instance, the user might not 
confirm the operation.) If this happens, you should abort the then the undo transaction with 
msgUndoAbort. See the comments on msgUndoAbort for more information. 



tifndef UNDO_INCLUDED 
tdefine UNDO_INCLUDED 

#ifndef LIST_INCLUDED 
♦include <list.h> 
tendif 



Types and Constants 



typedef STATUS UNDO_ID; // A transaction's id. 

♦define stsUndoAbortingTransaction MakeStatus (clsUndo, 1) 



♦define stsUndoDataFreed 

♦define undoStateNil 

♦define undoStateBegun flagO 

♦define undoStateUndoing flagl 

♦define undoStateRedoing flag2 

♦define undoStateAborting flag3 



MakeWarning{ clsUndo, 1) 



// Not implemented 



Exported Functions 



STATUS PASCAL 
InitClsUndo (void) ; 



Message Arguments 



UNDO ITEM 



typedef struct UNDO_ITEM { 

OBJECT object; // In: 

OBJECT subclass; // In: 

U16 flags; //In: 

P_UNKNOWN pData; //In: 

SIZEOF dataSize; // In: 

} UNDO ITEM, *P UNDO ITEM; 



object that undoes/ frees item 
See "Subclass Issues" section 
See "Memory Management" section 
See "Memory Management" section 
See "Memory Management" section 



The following flags are used in the flags field of an UNDO_ITEM. 



♦define ufReserved 
♦define ufClient 
♦define ufDataType 
♦define ufDatalnUndoHeap 
♦define ufDatalsHeapNode 
♦define ufDatalsObject 
♦define ufDatalsSimple 



(OxffOO) 

(f lagO I flagl | f lag2 | f lag3) 

(f lag4 1 flags | f lag6 1 flag? | ufReserved) 

flag4 

flags 

(flagS|flag4) 

(flag6|flag4) 



Other Message Arguments 



typedef struct UNDO_METRICS { 

UNDO_ID id; 

OS_HEAP_ID heapid; 

U16 state; 

U16 transactionCount; 

U16 itemCount; 

U32 limit; 

U32 resid; 

U32 info; 
} UNDO METRICS, *P UNDO METRICS; 



II 


In: Out 


II 


Out 


II 


Out 


II Out 


II 


Out 


II 


Out 


II 


Out 


II 


Reserved 



Nil => get current 
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♦define undoNewFields \ 
listNewFields \ 
UNDO_NEW_ONLY undo; 

typedef struct UNDO_NEW_ONLY { 

U32 reserved; // Reserved for expansion 

P_UNKNOWN pReserved; // Reserved for expansion 

U32 maxTransactions; 

} UNDO_NEW_ONLY, *P_UNDO_NEW_ONLY; 

typedef struct UNDO_NEW { 

undoNewFields 
} UNDO NEW, *P UNDO NEW; 



Messages 

Next: 1 1 ; recycled: none 



msgUndoAbort 

Aborts the current undo transaction. 

Takes pNulI, returns STATUS. 

#define msgUndoAbort MakeMsg(clsUndo, 10) 

Commerits The current transaction is flagged as being aborted. Until the transaction is closed, any attempted 

msgUndoAddltem, msgUndoBegin, and msgUndoEnd (including the one that finally closes the 
transaction) will fail and return stsUndoAbortingTransaction. Once the msgUndoEnd that closes the 
transaction is received, any remaining undo items in the aborted transaction are freed. 



msgUndoAddltem 

Adds a new item to the current undo transaction if and only if it is still open. 

Takes P_UNDO_ITEM, returns STATUS. 

tdefine msgUndoAddltem MakeMsg(clsUndo, 0) 

«ssa§e typedef struct UNDO_ITEM { 

rgometits OBJECT object; // In: object that undoes/frees item 

OBJECT subclass; // In: See "Subclass Issues" section 

U16 flags; // In: See "Memory Management" section 

P_UNKNOWN pData; // In: See "Memory Management" section 

SIZEOF dataSize; // In: See "Memory Management" section 

} UNDO_ITEM, *P_UNDO_ITEM; 

isiiments theUndoManager returns stsFailed if an open transaction does not exist. Any other error status indicates 

that there are not enough resources available to add the item. 



msgUndoBegin 

Creates a new undo transaction if there is no current transaction, or increments the nesting count if 
there is a current transaction. 

Takes RESJD, returns STATUS or UNDOJD. 

♦define msgUndoBegin MakeMsg(clsUndo, 1) 

See the "Nesting of msgUndoBegin and msgUndoEnd" section for information about how to send this 
message. 
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Messages 



leturn Value stsFailed Nesting limit exceeded. 

stsOK Returned status is actually the id of the new (or currently open) transaction. Cast it to type 
UNDOJD. 

The RES_ID for a transaction is determined by the first msgUndoBegin with a non-null argument. The 
string identified by the RESJD of the current undo transaction is used as the string for the "Undo" 
menu item. The RESJD should specify a resGrpTK string resource list. (This is analogous to the quick 
help strings that are found in the resGrpQHelp string resource list.) 

msgUndoCurrent " 

Undoes the most recent undo transaction. 



Takes pNull, returns STATUS. 

♦define msgUndoCurrent MakeMsg(clsUndo, 2) 

msgUndoCurrent undoes the most recent transaction. If a transaction is currently open the transaction 
is closed first, and then undone. 

It is unusual for a client to send this message. The only real reason for sending this message is if some 
piece of client code is implementing an alternative UI mechanism to invoke the undo mechanism. 



msgUndoEnd 

Decrements the nesting count of (and thus may end) the current transaction. 

Takes pNull, returns STATUS. 

#define msgUndoEnd MalceMsg(clsUndo, 3) 

See the "Nesting of msgUndoBegin and msgUndoEnd" section for information about how to send this 
message. 

StsFailed No open transaction. 



msgUndoGetMetrics 

Passes back the metrics associated with an undo transaction. 

Takes P_UNDO_METRICS, returns STATUS. 

♦define msgUndoGetMetrics MakeMsg(clsUndo, 4) 

Messoge typedef Struct UNDOJMETRICS { 

Arguments UNDO_ID id; // In: Out Nil => get current 

OS_HEAP_ID heapid; // Out 

U16 state; // Out 

U16 transactionCount; // Out 

U16 itemCount; // Out 

U32 limit; // Out 

U32 resid; // Out 

U32 info; // Reserved 
} UNDO_METRICS, *P_UNDO_METRICS; 

Comments Only an pArgs->id of Nil(UNDO_ID), representing the current undo transaction, is supported. 

Return Value StsFailed The specified transaction does not exist or there is in sufficient memory available to 

manipulate it. 
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msgUndoLimit 

Sets the maximum number of remembered undo transactions. 

Takes U32, returns STATUS. 

♦define msgUndoLimit MakeMsgCclsUndo, 8) 

Tlie default undo limit is 2. If your application wants to support a longer undo history, send 
msgUndoLimit to theUndoManager with the desired limit. 

If there are more transactions in the queue than the new limit, the extra transactions will be freed. 
Setting the limit to flushes all transactions and effectively disables undo until the limit is set to some 
non-zero value. 

msgUndoLimit always returns stsOK. 

msgUndoRedo 

Not implemented. 

Takes pNuIl, returns STATUS. 

#define msgUndoRedo MakeMsg(clsUndo, 5) 

Cominents Not implemented. Do not send this message. 

Client Messages 

msgUndoItem 

Sent to pArgs->object to have the item undone. 

Takes P_UNDO_ITEM, returns STATUS. 

#define msgUndoItem Ma]ceMsg(clsUndo, 6) 

fessoge typedef struct UNDO_ITEM { 

Irgomenfs OBJECT object; // In: object that undoes/frees item 

OBJECT subclass; // In: See "Subclass Issues" section 

U16 flags; // In: See "Memory Management" section 

P_UNKNOWN pData; // In: See "Memory Management" section 

SIZEOF dataSize; // In: See "Memory Management" section 

} UNDO_ITEM, *P_UNDO_ITEM; 

:ominents Note that the item will be freed in a separate step later. 

msgUndoFreeltemData 

Sent to pArgs->object to have pArgs->pData freed. 

Takes P_UNDO_ITEM, returns STATUS. 

Idefine msgUndoFreeltemData MakeMsg(clsUndo, 7) 

slessoge typedef struct UNDO_ITEM { 

Ir^uments OBJECT object; // In: object that undoes/frees item 

OBJECT subclass; // In: See "Subclass Issues" section 

U16 flags; // In: See "Memory Management" section 

P_UNKNOWN pData; // In: See "Memory Management" section 

SIZEOF dataSize; // In: See "Memory Management" section 
} UNDO_ITEM, *P_UNDO_ITEM; 

:omnients See the "Memory Management," "Subclass Issues" and "Freeing Undone Items" sections for information 

about how to respond to this message. 
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XFER.H 



This file contains the API definition for clsXfer and clsXferList. 

clsXfer inherits from clsStream. 

clsXfer defines the mechanisms used for transferring data between objects. 

clsXferList inherits from clsList. 

clsXferList is used by the transfer mechanism. 

Most clients of PenPoint's data transfer mechanism should use the procedural interfaces defined in this 
file. 

The functions described in this file are contained in XFER.LIB. 



Introduction 

Key Concepts 



This file describes some of PenPoint's support for transferring data. 

There are a few central concepts that underlie PenPoint's data transfer mechanism: 

♦ Sender and Receiver. There are two sides to any data transfer. "Sender" refers to the object providing 
the data and "Receiver" refers to the object receiving the data. These two objects can be in different 
processes, or in the same process. They can even be the same object! 

♦ Two Stages. Each PenPoint data transfer has two major stages. In the first stage the Sender and 
Receiver engage in a simple protocol to determine if the data can be transferred, and if so what 
"type" the data has. In the second stage, the data is actually transferred using a protocol that is 
specific to the type agreed to during Stage 1 . 

♦ Data Transfer Types. A Sender and Receiver need to agree on a data transfer type that they both 
understand. PenPoint defines several data transfer types and clients can define additional types. See 
the section "Determining a Data Transfer Type" for more information. 

♦ Data Transfer Protocol. Each data transfer type has an associated data transfer protocol. Once a 
transfer type has been agreed upon, the Sender and Receiver engage in the type-specific protocol to 
actually move the data. Note the same Data Transfer Protocol can be employed for multiple Data 
Transfer Types, but that each Data Transfer Type uses one and only one protocol. 



Roadmap 



Typical Receivers use the following to determine the desired data transfer type. 

♦ XferMatchO 

Typical Senders respond to or use the following to provide a list of data transfer types. 

♦ msgXferList 

♦ XferAddldsO 
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Typical Senders and Receivers who use data transfer types that use one-shot protocols use the following: 

♦ msgXferGet 

Senders and Receivers who use data transfer types that use stream-based protocols use the following: 

♦ msgXferStreamConnect 

♦ msgXferStreamWrite 

♦ msgXferStreamFreed 

♦ XferStreamConnectQ 

♦ XferStreamAcceptO 

Relationship betv/een Data Transfer and PenPoint's Ul 

PenPoint's data transfer mechanism is intentionally independent of the user interface that might trigger 
a data transfer. None of the interfaces defined in this file depend or define any part of a PenPoint 
application's user interface. 

However, the examples given in the commentary often use PenPoint's UI as an example of how a data 
transfer might be started. The file sel.h describes PenPoint's Move and Copy operations in detail. 

During a Move or Copy operation, the Sender object is the owner of the selection. The Receiver is the 
object upon which the move/copy icon was dropped and which receives msgSelMoveSelection or 
msgSelCopySelection as a result. The Receiver sends msgSeiOwner to theSelectionManager to get the 
Sender object and then engages in a data transfer with that object. 

A Typical Scenario 

A typical data transfer session goes something like this: 

♦ The Receiver decides that it is the receiving end of a data transfer operation. (For instance, the 
receiver might receive msgSelMoveSelection or msgSelCopySelection; see sel.h.) 

♦ The Receiver figures out the UID of the Sender object. (For instance, in the case of 
msgSelCopySelection or msgSelMoveSelection, the Sender object is the current selection owner, 
which can retrieved by sending msgSelOwner to theSelectionManager.) 

♦ The Receiver determines a mutually agreeable data transfer type using the utility routine XferMatch. 
(See section "Determining a Common Data Transfer Type" for more detailed information about 
XferMatch and alternatives.) 

♦ The Sender and Receiver use the Data Transfer Protocol associated with the agreed-upon type to 
actually transfer the data. 

Data Transfer Types 

A data transfer type is represented by a TAG. 

Below is a list of PenPoint's predefined data transfer types and the data transfer protocol associated with 
each. (The protocols are described in the next section.) 

xferString: one-shot using XFER_FIXED_BUF 

xferLongString: one-shot using XFER_BUF 

xferName: one-shot using XFER_FIXED_BUF 

xf erFullPathName : one-shot using XFER_FIXED_BUF 

xferRTF: stream 
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xferFlatLocator: one-shot using XFER_FIXED_BUF 

xferASCIIMetrics: one-shot using XFER_ASCII_METRICS 

xferScribbleObject: one-shot using XFER_OBJECT 

xferPicSegObject: one-shot using XFER_OBJECT 

In addition export. h and embedwin.h each define an additional data transfer type; see these files for 
more information. 

Determining a Common Data Transfer Type ^ 

The Sender and Receiver must agree on a data transfer type. < 

For instance, a note taking application might be willing to provide either xferScribbleObject or 
xferLongString data. A text editor might be willing to consume xferString, xferLongString or xferRTF 
data. Somehow the common data type (xferLongString) must be found and used. 

In PenPoint's data transfer mechanism, the Receiver is ultimately responsible for determining the 
mutually agreeable data transfer type. 

Typical Receivers can use a simply utility function, XferMatch, to compute the data transfer type. 
Typical Senders must respond to msgXferList and add data transfer types to the provided list with the 
utility function XferAddlds. 

(Most clients don't need to know about the inner workings of XferMatch, but they are documented in 
the section "Details of XferMatch" for sophisticated clients or the merely curious.) 

Data Transfer Protocols 

Each data transfer type uses a specific data transfer protocol. 
There are three types of protocols: 

♦ one-shot protocols 

♦ stream-based protocols 

♦ client-defined protocols 

One Shot Protocols 

Several data transfer types use a "One-Shot" protocol to transfer data. The protocols are called 
"one-shot" because all of the data can be transferred via a single message send. 

In all one-shot transfers, the Receiver uses ObjectSendUpdate to send msgXferGet to the Sender. 
(ObjectSendUpdate must be used because the Sender and Receiver might be in different processes.) 

The type of the pArgs to msgXferGet depends on the data transfer type ~ the specific types are 
described in the section "Data Transfer Types." However, all legal pArgs to msgXferGet have one thing 
in common ~ their first field is a data transfer type. The Receiver must fill in at least this field before 
sending msgXferGet so that the Sender can tell which data transfer type is being used. 

The Sender responds to msgXferGet by filling in pArgs as necessary. Some one-shot protocols require 
the Sender to allocate memory. (For instance, the xferLongString data transfer type requires that the 
sender allocate memory for pArgs->pBuf field of an XFER_BUF.) 

Some one-shot protocols require that Sender allocate memory. Any Sender-allocated memory must be 
allocated using OSHeapBlockAlloc and osProcessSharedHeapId. The Receiver must free this memory 
with OSHeapBlockFree. 
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Stream-Based Protocols 

Stream-based protocols make use of a specialized stream that is implemented by clsXferStream. 
clsXferStream adds the ability for two streams to be linked through an internal "pipe." 

Once a Receiver has decided to engage in a stream-based transfer (as described in the Section "A Typical 
Scenario" earlier), the steps in stream-based protocol are as follows: 

♦ The Receiver calls XferStreamConnect. 



♦ 



XferStreamConnect creates the Receiver's stream and then sends msgXferStreamConnect to the 
Sender. 



♦ In response to msgXferStreamConnect, the Sender calls XferStreamAccept. Essentially all Senders 
of stream-based protocols should pass self as the "Producer" parameter when they call 
XferStreamAccept ~ motivation and exceptions are described below. 

♦ XferStreamAccept properly creates the Sender's stream. 

♦ When control returns to it, the Receiver sends misgStreamReadData to its stream. 

♦ As a result of the Receiver's msgStreamReadData, the Sender receives msgXferStream Write. 

♦ In response to msgXferStreamWrite, the Sender writes data using msgStreamWriteData. 
IMPORTANT NOTE: In order to avoid overflowing internal buffers. Senders should not write 
huge chunks of data in a single call. Chunks than 64K won't work at all. Memory is used more 
efficiently if chunk sizes don't exceed lOK, although things will work at any size up to 64K. 

♦ The last two steps can be repeated any number of times. Eventually the Receiver gets stsEndOfData 
returned when sending msgStreamReadData. 

♦ The Receiver sends msgDestroy to its stream. 

♦ As a result of the Receiver's msgDestroy, the Sender receives msgXferStreamPree. 

♦ In response to msgXferStreaniFree, the Sender sends msgDestroy to its stream. 

The Sender must be prepared to handle msgXferStreamFreed at any time. (In addition to normal 
termination, msgXferStreamFreed can indicate that the Receiver has died or otherwise has prematurely 
destroyed its side of the pipe.) 

An Available Simplification 

Some Senders may know that they can contain only a limited amount of data. Or they may find the 
obligation to respond to msgXferStreamWrite multiple times and record how much data was actually 
written each time to be unduly burdensome. 

These Senders can pass objNull as the "Producer" parameter in their call of XferStreamConnect. As a 
result of doing this, msgXferStreamWrite will only be sent once, and in response these Senders should 
write all of their data in a single chunk. 

Client-Defined Protocols 

Clients can define their own data transfer types. There is a wide range of possibilities. Clients can use 
msgXferGet that use a new pArgs type. They can use streams but define structure on the data being 
streamed. Or they define an entirely new transfer protocol. 
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Other Information 



Details of XferMatch 

Most clients can simply use XferMatch without understanding how it works, but it's described here for 
specialized clients or the curious. 

XferMatch creates an instance of clsXferList 

It then sends msgXferList to the passed-in Sender. 

The Sender responds to msgXferList by adding items to the xfer list by calling XferAddlds. 

XferMatch then scans the two lists (one passed in by the Receiver and one filled in by the Sender) 
using the utility function XferListSearch. 

♦ If no mutually acceptable data transfer type is found, XferMatch returns stsNoMatch. Otherwise 
XferMatch returns stsOK and passes back the data transfer type in *pld. 

♦ Just before returning, XferMatch destroys the xferList. 

As an alternative to calling XferMatch, the Receiver could create the list, send msgXferList to the 
Sender, and then search the list for the best match (perhaps by using XferListSearch). 

Also, a sophisticated Sender can use m.sgListAddItem (rather than XferAddlds) to add the types to the 
list. 

Creating Instances of cIsXfer and clsXferList 

Normal clients of PenPoint's data transfer mechanism have no need to create instances of clsXfer and 
clsXferList. Instances are created internally when using the data transfer functions. 

tifndef XFER_INCLUDED 
tdefine XFER_INCLUDED 
tifndef CLSMGR_INCLUDED 
#include <clsmgr.h> 
#endif 

tifndef STREAM_INCLUDED 
tinclude <stream.h> 
tendif 

tifndef STREAM_INCLUDED 
tinclude <list.h> 
tendif 



Common #defines and typedefs 



Predefined Data Transfer Types 



tdefine xferString 
tdefine xferLongString 
tdefine xferName 
tdefine xferFullPathName 
tdefine xferRTF 
tdefine xferGoRTF 
tdefine xferFlatLocator 
tdefine xferASCIIMetrics 
tdefine xferScribbleObject 
tdefine xferPicSegObject 



MakeTag (clsXfer, 1) 

MakeTag (clsXfer, 2) 

MakeTag (clsXfer, 3) 

MakeTag (clsXfer, 4) 

MakeTag (clsXfer, 5) 

MakeTag (clsXfer, 6) 

MakeTag (clsXfer, 7) 

MakeTag (clsXfer, 10) 

MakeTag (clsXfer, 11) 

MakeTag (clsXfer, 12) 



// XferGet (FixedBuf) 

// XferGet (Buf) 

// XferGet (FixedBuf) 

// XferGet (FixedBuf) 

// Stream 

// Obsolete 

// XferGet (FixedBuf) 

// XferGet (AsciiMetrics) 

// XferGet (Object) 

// XferGet (Object) 
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XferList 

Normal clients need not create xferLists since the fUnctions create and destroy xferLists as needed. 
An xferList is a subclass of clsList that always allocates globally accessible memory for the list. 



tdefine XFER_LIST_NEW LIST_NEW 
tdefine P XFER LIST NEW P LIST NEW 



Messages 



msgXferList 

Ask Sender for its list of data transfer types. 

Takes OBJECT, returns STATUS. 

tdefine msgXferList MakeMsg(clsXfer, 1) 

Comnients This message is sent to the Sender to have the Sender provide the list of data transfer types it can 

provide. 

The Sender can add types to the passed-in list using either msgListAddltem or XferListAddlds. 

If the Sender has a preferred data transfer type, it should put this type at the beginning of the list. The 
Sender can use clsList messages to change the ordering of the list (see list.h). 

See Also msgListAddltems 

msgXferGet 

Sent by a Receiver to get "one-shot" data transfer information. 

Takes lots-of-things, returns STATUS. 

tdefine msgXferGet MakeMsg{clsXfer, 8) 

Comments msgXferGet is sent by the Receiver to the stream to retrieve the data being transferred. 

The type of this messages pArgs depends on the data transfer type being used. In all cases, the first field 
of pArgs must be a data transfer type so that the Sender (when it receives this message) knows what type 
of data to supply and what the true type of pArgs really is. 

iefyrst Vobe stsNoMatch specified data transfer type is inappropriate 

^ Variable Size Buffer 

This type is used as the pArgs of msgXferGet when the data transfer type is xferLongString. This type 
might also be used for client-defined data transfers. 

[The rest of this description is complicated by the reversal of names. The Receiver side of the data 
transfer operation sends msgXferGet and the the Sender side of the data transfer operation receives 
msgXferGet.] 

The Receiver (which sends msgXferGet) must set the "id" field to xferLongString. The Sender receives 
msgXferGet and fills in the rest of the structure. 

The Sender allocates the memory for pArgs->pBuf using OSHeapBlockAlloc from 
osProcessSharedHeapId. The Receiver must free this data using OSHeapBlockFree. 
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When used for xferLongString, the "pBuf ' field is a null-terminated string and the "len" field includes 
the terminating null character. (In other words, upon return, pArgs->len must equal 
(strlen(pArgs->pBuf) + 1).) 

typedef struct XFER_BUF { 

TAG id; // In: Data transfer type 

U32 data; // Unused: future use 

U32 len; // Out: Length of data in pBuf 

P_UNKNOWN pBuf; // Out: Buffer containing data 

// Must be SHARED and freed by caller ^ 

} XFER BUF, *P XFER BUF; m 

— — — ,/) 

3 

Fixed Size Buffer 

This type is used as the pArgs of msgXferGet when the data transfer type is ^ 

♦ xferString » 

♦ xferName 

♦ xferFullPathName 

♦ xferFlatLocator 

[The rest of this description is complicated by the reversal of names. The Receiver side of the data 
transfer operation sends msgXferGet and the the Sender side of the data transfer operation receives 
msgXferGet.] 

The Receiver (which sends msgXferGet) must set the "id" field to one of the data transfer types listed 
above. The Sender receives msgXferGet and fills in the rest of the structure. 

typedef struct XFER_FIXED_BUF { 

TAG id; // In: Data transfer type 

U32 data; // Unused. Reserved for future use 

U32 len; // Out: Length of data in buf 

U8 buf [300]; // Out: Buffer containing data 
} XFER_FIXED_BUF, *P_XFER_FIXED_BUF; 

Object Transfer 

This type is used as the pArgs of msgXferGet when the data transfer type is: 

♦ xferScribbleObject 

♦ xferPicSegObject. 

[The rest of this description is complicated by the reversal of names. The Receiver side of the data 
transfer operation sends msgXferGet and the the Sender side of the data transfer operation receives 
msgXferGet.] 

The Receiver (which sends msgXferGet) must set the "id" field to one of the data transfer types listed 
above, and must set the "receiver" field to self (or some other object in the Receiver's task). The Sender 
receives msgXferGet and fills in the rest of the structure. 

The Sender makes a copy of the object using msgCopy and returns the uid of the object in pArgs->uid. 
When the Sender sends msgCopy, it should use pArgs->receiver as the value of msgCopy's 
pArgs- > requestor. 

typedef struct XFER_OBJECT { 

TAG id; // In: Data transfer type 

OBJECT receiver; // In: Receiver 

OBJECT uid; // Out: Uid of object 

CLASS objClass; // Out: Class of object 

U32 reserved[4]; // Reserved for future use 

} XFER OBJECT, * P XFER OBJECT; 
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ASCII Metrics 

This type is used as tlie pArgs of msgXferGet when the data transfer type is xferASCIIMetrics. 

[The rest of this description is complicated by the reversal of names. The Receiver side of the data 
transfer operation sends msgXferGet and the the Sender side of the data transfer operation receives 
msgXferGet.] 

The Receiver (which sends msgXferGet) must set the "id" field to xferASCIIMetrics. The Sender 
receives msgXferGet and fills in the rest of the structure. 

"ASCII Metrics" include information about the character data that can be transferred from the Sender. 
In some cases (e.g. PenPoint's text component) it describes the selected text. 

(Essentially any Sender that can provide xferASCIIMetrics can also provide some type of character data 
~ typically xferString, xferLongString or xferRTF.) 

The "spare" field is always set to 0, The "first" field is offset of the first selected character. The "length" 
field is the number of characters in the selection. The "level" field describes which lexical unit the 
selection "contains." 

typedef struct XFER_ASCII_METRICS { 

TAG id; // In: data transfer type. 

U32 spare; // Out: always 

U32 first; // Out: character offset w.r.t. entire text 

// maxU32 implies a bad request 

U32 length; // Out: number of chars available to transfer 

U16 level; // Out: 0: undefined or unknown, 1: chars, 

// 2: words, 3: sentences, 4: paragraphs 

} XFER ASCII METRICS, *P XFER ASCII METRICS; 



Stream Specific Messages 



msgXferStreamConnect 

Sent to the Sender to ask it to link the Sender's and Receiver's pipe. 

Takes XFER_CONNECT, returns STATUS. 

#define msgXferStreamConnect MakeMsg{clsXfer, 2) 

Irgumerifs typedef Struct XFER_CONNECT { 

TAG id; // In: Id Receiver sent to XferStreamConnect 

OBJECT stream; // In: Stream created by Receiver 

P_UNKNOWN clientData; // In: clientData Receiver sent to 

// XferStreamConnect 
} XFER_CONNECT, *P_XFER_CONNECT ; 

inmmemfs The Sender responds by calling XferStreamAccept to complete the connection. 

In its call to XferStreamAccept, the Sender identifies the object that will generate the actual data, known 
as the Producer. Essentially all Senders should pass self as the value of Producer. 

See the section "Stream-Based Protocols" for more information. 



msgXferStreamAiixData 

Passes back auxiliary information associated with the pipe. 

Takes PP_UNKNOWN, returns STATUS. 

tdefine msgXferStreamAuxData MakeMsg(clsXfer, 4) 
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The Sender or Receiver can store auxiliary information with the pipe, using msgXferStreamSetAuxData 
and retrieve that information with msgXferStreamAuxData. 

This information can be used by either the Sender or Receiver to store private information or to or to 
pass information across the pipe. 

Warning: There is only one auxiliary data slot in the pipe. Only one of the Sender or Receiver should 
write the data, although both can read it. Subclasses must be aware of their ancestor's behavior in this 
regard. 

msgXferStreamSetAuxData ^ 



msgXferStreamSetAuxData 

Stores arbitrary client data with the pipe. 

Takes P_UNKNOWN, returns STATUS. 

tdefine msgXferStreamSetAuxData MakeMsg(clsXfer, 5) 

msgXferStreamAuxData 

msgXferStreamWrite 

Asks the Sender to write more data to the stream. 

Takes STREAM, returns STATUS. 

tdefine msgXferStreamWrite MakeMsg(clsXfer, 3) 

The Sender responds by writing to its stream using msgStreamWrite. 

The Sender may need access to its instance data to handle this message. The Sender can either 
implement its own facility for mapping from the stream to the necessary instance data (perhaps using 
properties; see clsmgr.h) or it can use msgXferStreamSetAuxData and msgXferStreamAuxData. 

See the section "Stream-Based Protocols" for more information. 

msgXferStreamFreed 

Sent to the Sender when the Receiver's side of the stream has been freed. 

Takes STREAM, returns STATUS. 

tdefine msgXferStreamFreed MakeMsg{clsXfer, 6) 

The Sender handles this message by sending msgDestroy to the stream passed in as a parameter. This 
means that both streams (and hence both ends of the "pipe") have been freed. 

See the section "Stream-Based Protocols" for more information. 



u 



Public Functions 



XferMatch 

The Receiver calls XferMatch to find a mutually acceptable data transfer type. 

Returns STATUS. 

STATUS EXPORTED XferMatch ( 

OBJECT Sender, // In: Sender to find match with 

TAG ids[], // In: Array of types the Receiver understands 

SIZEOF idsLen, // In: Length of the ids[] array 

P_TAG pid) ; // Out: matching data type 
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Comments See the section "Determining a Common Data Transfer Type" for detailed, information. 

iefyrn Valye stsNoMatch No common data transfer type could be found. 

non-error The common data transfer type is passed back in *pld. 
See Also XferListSearch 

XferListSearch 

Searches two sets of data transfer types for a match. 

Returns STATUS. 

function Prototype STATUS EXPORTED XferListSearch ( 

OBJECT listObject, // In: List object containing Sender types 

TAG ids[], // In: Array of types the Receiver understands 

SIZEOF idsLen, // In: Length of the ids[] array 

P_TAG pid); // Out: Matching data type 

Comsuefits Most clients of the data transfer mechanism use XferMatch rather than calling this function. 

XferListSearch scans the two sets of transfer types (one in listObject and one in the passed-in array) to 
find the best match. 

XferListSearch checks each item in listObject against each item in the array in order from to n-L 
Hence if the array contains [tagA, tagB] and the list contains [tabB, tagA], tagA is returned. Objects 
should put data types into the listObject or the array in order of most desired to least desired. 

Retyrii ¥«ltje stsNoMatch No common data transfer type could be found. 

non-error The common data transfer type is passed back in *pld. 

See Also XferMatch 



XferAddlds 

Adds data transfer types to listObject. 

Returns STATUS. 

n Prototype STATUS EXPORTED XferAddlds ( 
OBJECT listObject, 

TAG ids [ ] , 

SIZEOF idsLen) ; 

mts Typical Senders call this function while handling msgXferList. 

XferAddlds adds each item in the array of data transfer types to the list by sending msgListAddltem to 
listObject. 
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Stream Specific Functions 



XferStreamConnect 

A Receiver calls this function to create a stream connection to a Sender. 

Returns STATUS. 

cfion Profotyise STATUS EXPORTED XferStreamConnect ( „, 

OBJECT owner, // In: Sender to connect stream to in 

TAG id, // In: Desired data transfer type. (This is ^ 

// passed to Sender via msgXf erStreamConnect . ) ^ 

P_UNKNOWN clientData, // In: clientData. (This is passed to Sender 

// via msgXf erStreamConnect . ) 

P OBJECT pStream) ; // Out: Stream to perform msgStreamRead on 



>• 



See the section "Stream-Based Protocols" for more information. 

XferStreamAccept 

Called by Sender in response to msgXferStreamConnect. 

Returns STATUS. 

ttlon Prototype STATUS EXPORTED XferStreamAccept ( 

OBJECT connect, // In: pArgs->stream from msgXferStreamConnect 

U16 bufSize, // In: Size of transfer buffer (up to 64k) 

OBJECT Producer, // In: Object to receive msgXferStreamWrite 

P_OBJECT pStream) ; // Out: Stream for Sender side of the "pipe" 

iments As part of the Sender's response to msgXferStreamConnect, the Sender calls XferStreamAccept to 

properly create the Sender's side of the stream. 

See the section "Stream-Based Protocols" for more information. 
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ABMGR.H 



This file contains the API definition for theAddressBookMgr. 

theAddressBookMgr is an instance of a private class. It is the only instance of that class in the system. 

theAddressBookManager is a well known object that handles registration of and access to "system" 
address books. Registered address books are primarily responsible for managing the storage and retrieval 
of service specific addressing information. 

Registered address books adhere to the protocol defined in addrbookh. Information about its 
fiinctionality and use can be found there. 

theAddressBookMgr provides the facility to help other applications to provide a UI for picking the 
system address book. When an application wants to provide this pick list as an option card, it just needs 
to pass on msgOptionAddCards before it calls its ancestor to theAddressBookMgr. 
TheAddressBookMgr will do the rest. 

tifndef ABMGR_INCLUDED 
tdefine ABMGR_INCLUDED 

tinclude <uuid.h> 

#include <go.h> 

tdefine tagABMgrABList MakeTag (theAddressBookMgr, 1) 



Status Codes 



#define stsABMgrAddrBookNot Active 
tdefine stsABMgrAddrBookOpen 
tdefine stsABMgrNoneActive 
#define stsABMgrAddrBookNotRegistered 
#define stsABMgrNoOpenAddrBook 



MakeStatus (theAddressBookMgr, 1) 

MakeStatus (theAddressBookMgr, 2) 

MakeStatus (theAddressBookMgr, 3) 

MakeStatus (theAddressBookMgr, 4) 

MakeStatus (theAddressBookMgr, 5) 



Common #clefiiies and typedefs 



// Client is an application 

// Client is a service/data object 

// abmgr internal use only 



Enuml6(AB_MGR_ID_TYPE) { 

abMgrApplication = 0, 

abMgrObject = 1, 

abMgrNone =2, 

}; 
typedef struct AB_MGR_ID { 

CHAR name [nameBuf Length ] ; // Name of the address book 

AB_MGR_ID_TYPE type; // Address book object type 

union { 

OBJECT uid; // UID of the service/object 

UUID uuid; // UUID of the application working dir 

} value; 
} AB MGR ID, *P AB MGR ID; 
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Messages 



msgABMgrRegister 

Registers an application or a service as an address book instance. 

Takes P_AB_MGR_ID, returns STATUS. 

#define msgABMgrRegister MakeMsg{theAddressBookMgr, 1) 

typedef struct AB_MGR_ID { 

CHAR name [nameBuf Length] ; // Name of the address book 

AB_MGR_ID_TYPE type; // Address book object type 

union { 

OBJECT uid; // UID of the service/object 

UUID uuid; // UUID of the application working dir 

} value; 
} AB_MGR_ID, *P_AB_MGR_ID; 

When an instance of an address book is registered witli theAddressBookMgr, it can later be selected as 
"the system address book". 

Address books send this message to register themselves with theAddressBookMgr. Each instance of each 
address book should be registered with theAddressBookMgr. If an address book application is a subclass 
of clsAddrBookAppIication(see addrbook.h), then theAddressBookMgr automatically registers a newly 
created instance of this class. 

If an address book is an application, theAddressBookMgr will automatically re-registers the app on 
warm boot. If an address book is a service, however, it would have to re-register itself after a warm boot. 

msgABMgrUnregister 

Unregisters an application or a service as an address book instance. 

Takes P_AB_MGR_ID, returns STATUS. 

#define msgABMgrUnregister MakeMsg (theAddressBookMgr, 2) 

typedef struct AB_MGR_ID { 

CHAR name [nameBuf Length] ; // Name of the address book 

AB_MGR_ID_TYPE type; // Address book object type 

union { 

OBJECT uid; // UID of the service/object 

UUID uuid; // UUID of the application working dir 

} value; 
} AB_MGR_ID, *P_AB_MGR_ID; 

Address book send this message to theAddressBookMgr to unregister themselves. This is usually done 
when an application instance is deleted, or when a service is de-installed. If an address book application 
is a subclass of clsAddrBookApplication(see addrbook.h), then theAddressBookMgr automatically 
unregisters a deleted instance of this class. 

msgABMgrOpen 

Used by address book clients to begin access to address books. 

Takes nothing, returns STATUS. 

tdefine msgABMgrOpen MakeMsg (theAddressBookMgr, 3) 
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Comments Address book clients send msgABMgrOpen to theAddressBookMgr. If the system address book is an 

application, then theAddressBookMgr activates the application. If the system address book is a service, 
then theAddressBookMgr binds to the service (msgSMBind) 

Clients must call msgABMgrClose when they're finished with the address book. 

On warm boots, theAddressBookMgr requires that clients reopen the system address book. 

msgABMgrClose 

Used by address book clients to end access to address books. 

Takes nothing, returns STATUS. 

♦define msgABMgrClose MakeMsg (theAddressBookMgr, 4) 

Arguments typedef struct { 



BOOLEAN activated; | 

AB MGR ID addressBook; O 



} AB_MGR_LIST, *P_AB_MGR_LIST; 

Comments If the system address book is an application, then theAddressBookMgr deactivates the application. If 

the system address book is a service, then theAddressBookMgr binds to the service(msgSMUnbind). 

The address book is reference counted, so all msgABMgrOpen calls must be followed by an 
msgABMgrClose. 

msgABMgrList 

Creates a list of currently registered address book in pArgs. 

Takes P_LIST, returns STATUS. 

Idefine msgABMgrList MakeMsg (theAddressBookMgr, 5) 

Comments Every time msgABMgrList is called, a new list object is created. It is up to the client to call 

msgListFree(not msgDestroy) to destroy the list and the items in the list. Set the free mode to 
listFreeltemsAsData. 

Each element of the list is a P_AB_MGR_LIST. 

msgABMgrActivate 

Make a registered address book the system address book. 

Takes P_AB_MGR_ID, returns STATUS. 

♦define msgABMgrActivate MakeMsg (theAddressBookMgr, 6) 

Message typedef struct AB_MGR_ID { 

Arguments CHAR name [nameBuf Length] ; // Name of the address book 

AB_MGR_ID_TYPE type; // Address book object type 

union ( 

OBJECT uid; // UID of the service/object 

UUID uuid; // UUID of the application working dir 

} value; 
} AB_MGR_ID, *P_AB_MGR_ID; 

Comments In the current implementation only one address book can be the system address book at a time. If there 

is currently a system address book, that address book is deactivated first. 

Clients that are applications set the type field to 'application' and set the value field to the UUID of 
their application working directory. Clients that are services or data objects set the type field to 'object' 
and set the value field to their object UID. 



u 
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tetorrs ¥«iye stsABMgrAddrBookOpen The current system address book is currently open, therefore it can not be 

deactivated 

stsABMgrAddrBookNotRegistered The address book identified by pArgs is not a registered address 
book. 

msgABMgrDeactivate 

Deactivates the current system address book. 

Takes P_AB_MGR_ID, returns STATUS. 

tdefine msgABMgrDeactivate MakeMsg (theAddressBookMgr, 7) 

Messoge typedef struct AB_MGR_ID { 

Argyrtienfs CHAR name [naitieBuf Length] ; // Name of the address book 

AB_MGR_ID_TYPE type; // Address book object type 

union { 

OBJECT uid; // UID of the service/object 

UUID uuid; // UUID of the application working dir 

} value; 
} AB_MGR_ID, *P_AB_MGR_ID; 

Seforri ¥«iiie StsABMgrAddrBookOpen The current system address book is currently open, therefore it can not be 

deactivated 



msgABMgrlsActive 

Indicates if the specified AB_MGR_ID is currently set. 

Takes P_AB_MGR_ID, returns STATUS. 

#define msgABMgrlsActive MakeMsg (theAddressBookMgr, 8) 

ssssge typedef struct AB_MGR_ID { 

gyments CHAR name [nameBuf Length] ; // Name of the address book 

AB_MGR_ID_TYPE type; // Address book object type 

union { 

OBJECT uid; // UID of the service/object 

UUID uuid; // UUID of the application working dir 

} value; 
} AB_MGR_ID, *P_AB_MGR_ID; 

turn ¥akm stsOK Specified id is activated. 

stsABMgrNotActive Specified id is not activated, but something is active. 

stsABMgrNoneActive No address book is currently active. 



Observer Messages 



msgABMgrChanged 

Sent to observers of theAddressBookMgr when the system address book changes. 

Takes P_AB_MGR_NOTIFY, returns STATUS. 

tdefine msgABMgrChanged MakeMsg (clsAddressBook, 9) 



I,rgyments 



Enuml6(AB MGR CHANGE TYPE) { 
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abMgrRegister 


= 0, 


abMgrUnregister 


= 1, 


abMgrActivated 


= 2, 


abMgrDeactivated 


= 3, 


abMgrOpened 


= 4, 


abMgrClosed 

}; 


= 5, 


i 1 

typedef struct { 




AB_MGR_CHANGE_TYPE 


type; 


AB_MGR_ID 


addressBook; 


} AB MGR NOTIFY, *P AB 


MGR NOTIFY; 



// an ab has been registered 



pArgs->activated is set to TRUE if pArgs->addressBook is made the system address book, and to FALSE 
if pArgs->addressBook has been deactivated as the system address book. 







:WMMt^ -r^^^^^ 
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ADDRBOOK.H 



clsAddressBook inherits from clsObject. 

This header file defines the address book protocol. 

The address book protocol defines what minimal set of information is to be kept by an address book 
app or service, how information is to be stored, retrieved, queried by an address book client. Please refer 
to abmgr.h for information on address book manager. 

All requests to access address book information is channeled through the address book manager. There 
can be multiple address book clients at one time. Whether or not address book clients can access 
information from more than 1 address book application/service simultaneously is completely up to the 
implementation of the address book manager. The current implementation of theAddressBookMgr 
provided by GO only allows access to one address book at a time. 

Because theAddressBookMgr uses ObjectSend to relay messages to address books, pointers in pArgs in 
any address book protocol messages should point to some shared memory space. 

There are 3 major types of address information defined by the protocol: 

♦ individual personal information(e.g.name, phone number, street address) 

♦ service information(individual's fax phone number, email address, etc) 

♦ distribution list information 

All information is kept/retrieved in attribute-value form. The basic entity in an address book is an 
"entry"; all information is presented relative to an entry. E.g. to access any information in an address 
book, a "key" to an entry must be presented. Within an entry, a client can set/get entry related 
information(name, street address, etc.). Service address information is also kept as part of an entry. 
Because there can be multiple service addresses for each entry(e.g. an individual has 2 fax numbers and 1 
email address), a service address is accessed through a "service id" or the name of the service, (e.g. service 
name = "fax") 

The Address Book Protocol specifies a minimum set of attributes and attribute types to be supported by 
third party address book applicaitons or services. If a developer thinks that some addition attributes or 
attribute types are common enough that they should be defined in the protocol, please contact GO 
Corporation Developer Support. 

tifndef ADDRBOOK_INCLUDED 

tdefine ADDRBOOK_INCLUDED 

tifndef GO_INCLUDED 

# include <go.h> 

#endif 

tifndef UID_INCLUDED 

tinclude <uid.h> 

tendif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef DIALENV_INCLUDED 

tinclude <dialenv.h> 

tendif 
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Common #clefines and typedefs 



All address book apps should be a sub-class of this app. Being a sub-class of clsAddrBookApplication 
frees an address book application from having to register, and unregister itself w/ TheAddressBookMgr. 
TheAddressBookMgr will notice when an instance of clsAddrBookApplication has been 
created/destroyed, and will automatically register/unregister the instance. Aside from providing this auto 
registeration/unregisteration, clsAddrBookApplication provides no other special behavior to its 
sub-class. 



#define clsAddrBookApplication 



MakeWKN(3284, 1, wknGlobal) 



Pre-defined Attribute Types 



#define abNuitiber 
#define abString 
#define abPhoneNumber 
#define abOther 



MakeTag(clsAddressBook, 0) // 32-bit number 



MakeTag(clsAddressBook, 1) 
MakeTag(clsAddressBook, 2) 
MakeTag(clsAddressBook, 3) 



// null-terminated string 
// DIALENV_TELEPHONE_NUMBER 
// some encoded byte array 
// interpreted by address 
// books simply as a byte 
// stream 



Pre-defined attribute ids 



#define AddrBookGroupNameld MakeTag(clsAddressBook, 
#define AddrBookGivenNameld MakeTag(clsAddressBook, 
Idefine AddrBookSurNameld MakeTag(clsAddressBook, 
Idefine AddrBookHomePhoneld MakeTag(clsAddressBook, 
#define AddrBookBussPhoneld MakeTag(clsAddressBook, 
#define AddrBookCountryld MakeTag(clsAddressBook, 



0) // abString 

1) // abString 

2) // abString 

3) // abPhoneNumber 

4) // abPhoneNumber 

5) // country in post 
// addr, abString 
// state or prefe- 
// cture, abString 

7) // zip, abString 

8) // city , abString 

9) // ku in Japanese 
// addr, abString 

AddrBookStreetId represents street, number, building and other addressing information, the character 
\012(LF in ASCII) can be used to separate the different parts. E.g. a street address can be 2650 Durant 
Avenue Deutsch Hall #406 In this case, the address should be stored in AddrBookStreetId as "2650 
Durant Avenue\012Deutsch Hall #406" 



#define AddrBookStateld 

Idefine AddrBookZipId 
Idefine AddrBookCityld 
Idefine AddrBookDistrictId 



MakeTag(clsAddressBook, 6) 



MakeTag (clsAddressBook, 
MakeTag (clsAddressBook, 
MakeTag (clsAddressBook, 



Idefine AddrBookStreetId MakeTag (clsAddressBook, 10) 
Idefine AddrBookCompanyld MakeTag (clsAddressBook, 11) 

Idefine AddrBookTitleld MakeTag (clsAddressBook, 18) 



Idefine AddrBookPositionId MakeTag (clsAddressBook, 19) 



Idefine AddrBookNickNameld MakeTag (clsAddressBook, 20) 



Idefine AddrBookBussPhone2Id MakeTag (clsAddressBook, 



Idefine AddrBookFaxId MakeTag (clsAddressBook, 22) 



Idefine AddrBookSvcNameld MakeTag (clsAddressBook, 12) 



// abString 

// company name, 

// abString 

// title of an 

// individual entry 

// abString 

// position of an 

// individual entry 

// abString 

// nickname of an 

// individual entry 

// abString 

21) // 2nd bussiness 

// phone I 

// abPhoneNumber 

// fax I of an 

// individual entry 

// abPhoneNumber 

// name of svc, 

// abString 
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#define AddrBookSvcNoteld MakeTag(clsAddressBook, 13) // user defined 

// SVC nickname 
// abString 

♦define AddrBookSvcShortId MakeTag(clsAddressBook, 14) // service short 

// address 

The following two special id's are used in specifying a query 

tdefine AddrBookEntryKeyld MakeTag(clsAddressBook, 15) 
♦define AddrBookSvcIdId MakeTag{clsAddressBook, 16) 

This is the type for address book transfer protocol. If an address book supports move/copy protocol, 
then it should transfer an entry in a XFER_BUF structure, where XPER_BUF.pBuf is a pointer to 
ADDR_BOOK_ENTRY structure. 

♦define AddrBookXferType MakeTag(clsAddressBook, 17) 

♦define AddrBookAll (maxU16) 

♦define AddrBookAllSvcSelectAttrs (maxUl6-l) 

♦define AddrBookSelectSvcSelectAttrs (maxU16-2) 

♦define AddrBookSelectSvcAllAttrs .(maxUl6-3) 

If the client wants all attributes(either all entry attributes or all service attributes.), the address book 
should return the attributes in some well-known order. The next batch of #define's specifies the order for 
the common fields 



♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 
♦define 

♦define 
♦define 
♦define 

typedef 
typedef 
typedef 
typedef 
typedef 
typedef 
typedef 



AddrBookSurNamelndex 

AddrBookGivenName Index 

AddrBookHomePhonelndex 

AddrBookBussPhonelndex 

AddrBookCountrylndex 

AddrBookStatelndex 

AddrBookZipIndex 

AddrBookCitylndex 

AddrBookDistrict Index 

AddrBookStreetlndex 

AddrBookCompanylndex 

AddrBookTitlelndex 

AddrBookPositionlndex 

AddrBookNickNamelndex 

AddrBookBussPhone2 Index 

AddrBookFaxIndex 

AddrBookSvcNamelndex 

AddrBookSvcNote Index 

AddrBookSvcShort Index 



9 

10 

11 

12 

13 

14 

15 


1 
2 



P_UNKNOWN ADDR_BOOK_SERVICE_ID, 

TAG ADDR_BOOK_ATTR_ID, 

TAG ADDR_BOOK_ATTR_TYPE, 

U16 ADDR_BOOK_ATTR_LENGTH, 

P_UNKNOWN ADDR_BOOK_ATTR_VALUE, 

P UNKNOWN ADDR BOOK KEY, 



*P_ADDR_BOOK_SERVICE_ID ; 
*P_ADDR_BOOK_ATTR_ID ; 
*P_ADDR_BOOK_ATTR_T YPE ; 
*P_ADDR_BOOK_ATTR_LENGTH ; 
*P_ADDR_BOOK_ATTR_VALUE ; 
*P ADDR BOOK KEY; 



CHAR ADDR BOOK ATTR LABEL [nameBuf Length ] ; 



ADDR_BOOK_ATTR.length is the length of ADDR_BOOK_ATTR. value. The following table lists what the 
length field mean, given a certain attribute type: 



Attr Type 



length 



abString length of the string 

abNumber SizeOf(U32) 

abPhoneNumber SizeOf {DIALENV_TELEPHONE_NUMBER) 

abOther length of attribute in bytes 
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The following table lists what the value field should be, given a certain attribute type: 
Attr Type value 



abString 
abNumber 
abPhoneNumber 
abOther 



a ptr to actual storage of the str 

the number itself 

P_D I ALENV_TELEPHONE_NUMBER 

a ptr to a byte array that 

contains the attribute. 



// length of value, in bytes 
// for display purpose 



// for display purpose 



// uniquely identify a svc inst 



abString a ptr to actual storage of the str 
abNumber the number itself 

abPhoneNumber P_DIALENV_TELEPHONE_NUMBER 
abOther a ptr to a byte array thatcontains the attribute. 

typedef struct ADDR_BOOK_ATTR { 

ADDR_BOOK_ATTR_ID id; 

ADDR_BOOK_ATTR_TYPE type; 

ADDR_BOOK_ATTR_LENGTH length; 

ADDR_BOOK_ATTR_VALUE value; 

ADDR_BOOK_ATTR_LABEL label; 

} ADDR_BOOK_ATTR, *P_ADDR_BOOK_ATTR; 

typedef struct ADDR_BOOK_ATTR_DESC { 

ADDR_BOOK_ATTR_ID id; 

ADDR_BOOK_ATTR_TYPE type; 

ADDR_BOOK_ATTR_LABEL label; 

} ADDR_BOOK_ATTR_DESC, *P_ADDR_BOOK_ATTR_DESC; 

typedef struct ADDR_BOOK_SERVICE { 

ADDR_BOOK_SERVICE_ID svcid; 

U16 numAttrs; 

P_ADDR_BOOK_ATTR attrs; 

} ADDR_BOOK_SERVICE, *P_ADDR_BOOK_SERVICE; 

Enuml 6 ( ADDR_BOOK_ENTRY_TYPE ) { 

ablndividual =0, 

abGroup =1, 

}; 
tdefine abMaxSvcNameMatch 5 

typedef struct ADDR_BOOK_SERVICE_QUAL { 

U16 numAttrlds; 

P_ADDR_BOOK_ATTR_ID svcAttrlds; 

Ul 6 numS vcName s ; 

CHAR svcNames [abMaxSvcNameMatch] [nameBuf Length] ; 

} ADDR_BOOK_SERVICE_QUAL, *P_ADDR_BOOK_SERVICE_QUAL; 

.heap field is an in-parameter in msgAddrBookGet and msgAddrBookSearch, it is not applicable for 
other msgs. A client should specify the heap id of the heap that it would like space allocated. Typically a 
client would use OSTaskSharedHeapId(clientsTaskld). A client should not use osProcessSharedHeapId 
or osProcessHeapId because they refer to different heaps in dififferent processes. It is very important that 
clients free allocated space. 

typedef struct ADDR_BOOK_ENTRY { 

OS HEAP ID heap; 



ADDR BOOK ENTRY TYPE 


type; 


ADDR BOOK KEY 




key; 


U16 




nimiAttrs; 


P ADDR BOOK ATTR 




attrs; 


U16 




numServices; 


P ADDR BOOK SERVICE 


services; 


ADDR BOOK SERVICE 


QUAL 


svcQual; 



// where should the address 

// book alloc necessary space 

// applicable only for 

// msgAddrBookGet and 

// msgAddrBookSearch 



// Read only, ablndividual only 

// ablndividual only 

// service qualifier, for Get 



} ADDR BOOK ENTRY, *P ADDR BOOK ENTRY; 
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Status Codes 



Error Status Values 



#define stsAddrBookBufTooSmall 
tdefine stsAddrBookEntryExists 
tdefine stsAddrBookSvcDataExists 
♦define stsAddrBookEntryNotFound 
#define stsAddrBookSvcNotFound 
tdefine stsAddrBookBadKey 
tdefine stsAddrBookUnknownType 
tdefine stsAddrBooklnvalidAttr 
tdefine stsAddrBookReadOnlyAttr 
tdefine stsAddrBookDuplicateAttrld 



Non Error Status Values 



tdefine stsAddrBookGroupEntry 
tdefine stsAddrBookNotSupported 



MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 
MakeStatus 



(clsAddressBook, 1) 

(clsAddressBook, 2) 

(clsAddressBook, 3) 

(clsAddressBook, 4) 

(clsAddressBook, 5) 

(clsAddressBook, 6) 

(clsAddressBook, 7) 

(clsAddressBook, 8) 

(clsAddressBook, 9) 

(clsAddressBook, 10) 



MakeWarning (clsAddressBook, 7) 
MakeWarning (clsAddressBook, 8) 



Messages 



msgAddrBookGet 

fills in the specified entry field data, given an address book key for the entry. 

Takes P_ADDR_BOOK_ENTRY, returns STATUS. 

tdefine msgAddrBookGet 

typedef struct ADDR_BOOK_ENTRY { 



MakeMsg (clsAddressBook, 1) 



OS HEAP ID 



heap; 



ADDR_BOOK ENTRY_TYPE 


type; 


ADDR BOOK KEY 




key; 


U16 




numAttrs; 


P ADDR BOOK ATTR 




attrs; 


U16 




numServices; 


P_ADDR_BOOK_SERVICE 


services; 


ADDR BOOK SERVICE 


QUAL 


svcQual; 



// where should the address 

// book alloc necessary space 

// applicable only for 

// msgAddrBookGet and 

// msgAddrBookSearch 



// Read only,abIndividual only 

// ablndividual only 

// service qualifier, for Get 



} ADDR BOOK ENTRY, *P ADDR BOOK ENTRY; 



If attribute type is abString and the client-provided space is not big enough, stsAddrBookBufrooSmall 
is returned, and as much information as there is room for is filled in (null-terminated). Similarly, if 
attribute type is abOther, StsAddrBookBufrooSmall is returned, and the client-provided buffer is filled 
in(w/o null-termination). 

Parameters: 

pArgs->key In: specify from which entry to get info 

pArgs->type Out: type of the entry 

pArgs->numAttrs In: number of elements in pArgs->attrs array. Each of pArgs->attrs.id specifies the 
id of the attribute the client wants the address book to return. If the client sets this field to 
AddrBookAll, then the address book will return all entry attributes (excluding services), and it will 
allocate the necessary space. The client needs to deallocate the space. If the field is set to 0, then no 
attributes are returned. Out: number of attributes returned 
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pArgs->attrs[x].id In: which attributes to get 

pArgs->attrs[x].type Out: attribute type 

pArgs->attrs[x]. length Out: attribute length of each attr specified in entryAttrlds. See previous table 
on attribute type-attribute length. 

pArgs->attrs[x] .value In: if this field is pNull, the address book will allocate space for the value. Out: 
attribute value, see previous table on attribute value-attribute length, 

pArgs->attrs[x]. label Out: attribute label, for display. 

pArgs->numServices In: number of elements in pArgs->services array The client should specify 
AddrBookAll here if it wants all services and all service attributes for each service. If it wants only 
selective attributes from all services, then set numServices to AddrBookAllSvcSelectAttrs. If it wants 
all attributes from selective services, then set numServices to AddrBookSelectSvcAlIA.ttrs. Lastly, if 
the client wants selective attrs from selective svcs, then set numServices to 

AddrBookSelectSvcSelectAttrs.In all cases, the address book will allocate the necessary storage for all 
info, which needs to be freed by the client. If the field is set to 0, then no service information is 
returned Out: number of services returned. 

pArgs->svcQual In: If numServices is AddrBookAllSvcSelectAttrs, or AddrBookSelectSvcSelectAttrs, 
then numAttrlds is the number of elements in the svcAttrlds array, and svcAttrlds contains the ids 
of the attributes whose values should be retrieved. If numServices is AddrBookSelectSvcAllAttrs or 
AddrBookSelectSvcSelectAttrs,then numSvcNames is the number of elements in the svcNames 
arra)'^, and svcNames contains the names of services whose attribute values should be retrieved. For 
any other values of numServices, this field is irrelevent. 

pArgs->services Out: Allocated space if so requested. 

pArgs->services[y].svcId In: For each services specifically requested (as opposed to using AddrBookAll 
or AddrBookAllSvcsSelectAttrs, and other such constants in pArgs->numServices), there needs to be 
a svcid, telling the address book which service to return 

pArgs->services[y].attrs:In/Out: analogous to pArgs->attrs 



msgAddrBookSet 

Sets the specified entry and service data . 

Takes P_ADDR_BOOK_ENTRY, returns STATUS. 

#define msgAddrBookSet 

typedef struct ADDR_BOOK_ENTRY { 

OS_HEAP_ID heap; 



ADDR_BOOK_ENTRY_TYPE 


type; 


ADDR BOOK KEY 




key; 


U16 




numAttrs; 


P ADDR BOOK ATTR 




attrs; 


U16 




numServices ; 


P_ADDR_BOOK_SERVICE 


services; 


ADDR BOOK SERVICE 


QUAL 


svcQual; 



MakeMsg(clsAddressBook, 2) 

// where should the address 
// book alloc necessary space 
// applicable only for 
// msgAddrBookGet and 
// msgAddrBookSearch 



// Read only,abIndividual only 

// ablndividual only 

// service qualifier, for Get 



} ADDR BOOK ENTRY, *P ADDR BOOK ENTRY; 
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Comments Parameters: 

pArgs->key In: specify from which entry to get info 

pArgs->numAttrs In: how many attributes in the entry to set 

pArgs->attr[x].id In: which attributes to set 

pArgs->attr[x].type NA: don't need to specify 

pArgs->attr[x]. length In: client-specified size of the correspond- ingentryAttrValue field, mandatory 
for abOther, unnecessary for other types. 

pArgs->attr[x] .value In: attribute value, see previous table on attribute value-attribute length. 

pArgs->numServices In: number of services to set. Set it to if not setting any service info 

pArgs->svcAttrIds NA: not applicable 

pArgs->services[y].svcId In: service id of the service that set applies to 

pArgs->services[y].attrs In: analogous to pArgs->attrs. 

msgAddrBookAdd 

Adds the specified entry and service data. 
Takes P_ADDR_BOOK_ENTRY, returns STATUS. 
#define msgAddrBookAdd 






typedef struct ADDR_BOOK_ENTRY { 

OS_HEAP_ID heap; 



ADDR BOOK ENTRY TYPE 


type; 


ADDR BOOK KEY 




key; 


U16 




numAttrs; 


P ADDR BOOK ATTR 




attrs; 


U16 




numServices ; 


P ADDR BOOK SERVICE 


services; 


ADDR BOOK SERVICE 


QUAL 


svcQual; 



MakeMsg (clsAddressBook, 3) 



// where should the address 

// book alloc necessary space 

// applicable only for 

// rasgAddrBookGet and 

// msgAddrBookSearch 



// Read only,abIndividual only 

// ablndividual only 

// service qualifier, for Get 



} ADDR_BOOK_ENTRY, *P_ADDR_BOOK_ENTRY; 
Parameters: 



pArgs->key In: If the msg is used to add a service addr then the client specifies the entry key of the 
entry to which we add the service address. Out: if the msg is used to add an entry, then address 
book fill this field w/ the key of the entry just added 

pArgs->numAttrs In: how many attributes in the entry to have specified initial values. 

pArgs->attr[x].id In: which attributes to add. To add a brand new individual entry, then at least 
AddrBookGivenNameld or AddrBookSurNameld need to be specified. To add a group entry, 
AddrBookGroupNameld needs to be specified. 

pArgs->attr[x] .type NA: don't need to specify 

pArgs->attr[x]. length In: mandatory if attribute type is abOther 

pArgs->attr[x] .value In: attribute value, see previous table on attribute value-attribute length. 

pArgs->numServices In: number of services to set. Set it to if not adding any service info 

pArgs->svcAttrIds NA: not applicable 
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pArgs->services[y].svcId Out service id of the service just added 
pArgs->services[y].attrs In analogous to pArgs->attrs. 

msgAddrBookDelete 

Deletes the specified entry and service data , 
Takes P_ADDR_BOOK_ENTRY, returns STATUS. 
tdefine msgAddrBookDelete 
typedef struct ADDR BOOK ENTRY { 



OS HEAP ID 



heap; 



ADDR_BOOK_ENTRY_TYPE 


type; 


ADDR BOOK KEY 




key; 


U16 




numAttrs; 


P ADDR BOOK ATTR 




attrs; 


U16 




numServices; 


P ADDR BOOK SERVICE 


services; 


ADDR BOOK SERVICE 


QUAL 


svcQual; 



MakeMsg(clsAddressBook, 4) 

// where should the address 
// book alloc necessary space 
// applicable only for 
// msgAddrBookGet and 
// msgAddrBookSearch 



// Read ohly,abIndividual only 

// ablndividual only 

// service qualifier, for Get 



} ADDR_BOOK_ENTRY, *P_ADDR_BOOK_ENTRY; 

Parameters: 

pArgs->key In: entry id of the entry to be deleted. If deleting a service, then this field still needs to be 
specified. Only the specified service is deleted. 

pArgs->numServices In: number of services to delete. Set it to if deleting the entire entry. 

pArgs->services[x].svcId In Id's of the services to be deleted 

All other fields in ADDR_BOOK_ENTRY structure are not applicable. 



msgAddrBookSearch 

Searches for the entry that matches the search spec. 
Takes P_ADDR_BOOK_SEARCH, returns STATUS. 
tdefine msgAddrBookSearch 
Enuml6(ADDR BOOK SEARCH TYPE) { 



MakeMsg(clsAddressBook, 5) 



abSearchlndividuals = 0, 
abSearchGroups = 1, 
abSearchAll = 2, 



// Enumerate address book entries 

// Enumerate groups 

// Enumerate all entries 



}; 

Enuml6(ADDR_B00K_SEARCH_DIR) {' 

abEnumNext = 0, // Search forward 

abEnumPrevious =1 // Search backwards 
}; 
Enuml 6 ( ADDR_BOOK_ATTR_OP S ) { 

abAnd = 0, 

abOr = 1 
}; 
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Enuml6(ADDR BOOK VALUE OPS) { 



abEqual = 0, 






abNotEqual = 1, 






abGreater = 2, 






abLess = 3, 






abGreaterEqual = 4, 






abLessEqual = 5, 






abMatchBeginning = 6, 


// 


string matching 


abMatchEnd = 7, 


// 


string matching 


abMatchPartial = 8, 


// 


string matching 



abMaxValue = abMatchPartial 



Commepfs 



If a client wants to specify a query that says "match an entry whose last name is "Smith" and whose zip 
code is "94024", then the .query field in pArgs for msgAddrBookSearch would have 2 elements: 

pArgsquery id length value valueOp attrOp 

attr[0] AddrBookGivenNameld N/A Smith abEqual abAnd 

attr[l] AddrBookZipId N/A 94024 abEqual N/A 

Essentially, the attrOp field specifies the operator between attr[x] and attr[x+l]. valueOp specifies the 
relationship between the attribute id and its specified value, e.g. (a == 1) AND (b == 2), the "=="'s are 
valueOp, "AND" is an attrOp. By definition, pArgs->attrs[pArgs->numAttrs-l]. attrOp does not need 
to be specified. 

typedef struct ADDR_BOOK_QUERY_ATTR { 

ADDR_BOOK_ATTR_ID id; 

ADDR_BOOK_ATTR_LENGTH length; 

ADDR_BOOK_VALUE_OPS valueOp; 

ADDR_BOOK_ATTR_VALUE value; 

ADDR_BOOK_ATTR_OPS attrOp; 
} ADDR_BOOK_QUERY_ATTR, *P_ADDR_BOOK_QUERY_ATTR; 

typedef struct ADDR_BOOK_QUERY { 

U16 numAttrs; 

P_ADDR_BOOK_QUERY_ATTR attrs; 
} ADDR_BOOK_QUERY, *P_ADDR_BOOK_QUERY ; 

typedef struct ADDR_BOOK_SEARCH { 

Starting Pt. Out: Result 

look for the nth entry meeting 
the search criteria, nth = 1 
if looking for the first entry 
meeting the search criteria. 



what to look for, set query to 
pNull to enumerate 
: result entry 



pArgs->key is the pArgs->nth entry that matches the search spec, sorted by the attribute specified in 
pArgs->sort, the entry is just before/ after(depending on the value of pArgs->dir) of pArgs->key If key is 
nil, the enumeration starts with the first element if abEnumNext is specified, and the last element if 
abEnumPrevious is specified. 

Parameters: 

pArgs->key In Start point of the search Out:Resulting entry id of the match 

pArgs->nth In Look for the nth enty meeting the search criteria 

pArgs->sort In Attribute id of the attribute that the result should be sorted by 



ADDR BOOK KEY 


key; 


// In: 


ADDR BOOK SEARCH TYPE 


type; 


// In: 


U32 


nth; 


// In: 
// 
// 
// 


ADDR BOOK ATTR ID 


sort ; 




ADDR BOOK SEARCH DIR 


dir; 




ADDR BOOK ENTRY TYPE 


outType 


; 


ADDR_BOOK_QUERY 


query; 


// In: 
// 


ADDR BOOK ENTRY 


result; 


// Out 


} ADDR BOOK SEARCH, *P ADDR BOOK SEARCH; 
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pArgs->dir In search backwards or forwards. 

pArgs->outType Out: type of die matched entry 

pArgs->query In an elaborate explanation is available below 

pArgs->result In How each field is specified is the same as that for msgAddrBookGet. Except for the 
key field, which will be filled in by msgAddrBookSearch Out:same as msgAddrBookGet 

msgAddrBookGetServiceDesc 

Gets the service address description from the address book. 

Takes P_ADDR_BOOK_SERVICES, returns STATUS. 

tdefine msgAddrBookGetServiceDesc MakeMsg(clsAddressBook, 9) 

#define abServiceDescFields \ 

CHAR name [nameBuf Length] ; \ 

U16 maxPerEntry; \ 

U16 numAttrs; \ 

P_ADDR_BOOK_ATTR_DESC attrs; \ 

Arguments typedef struct ADDR_BOOK_SVC_DESC { 

abServiceDescFields 
} ADDR_BOOK_SVC_DESC, *P_ADDR_BOOK_SVC_DESC ; 

typedef struct ADDR_BOOK_SERVICES { 

OS_HEAP_ID heap; 

U16 numServices; 

P_ADDR_BOOK_SVC_DESC services; 
} ADDR_BOOK_SERVICES, *P_ADDR_BOOK_SERVICES ; 

Comments Parameters: 

pArgs->numServices Out: number of installed services an array of ADDR_BOOK_SVC_DESC's is 
allocated and should be freed by the caller. 

Usfum Voioe StsOK 

msgAddrBookEnumGroupMembers 

Enumerates through the members in a group. 

Takes P_ADDR_BOOK_ENUM_GROUP_MEMBER, returns STATUS. 

#define msgAddrBookEnumGroupMembers MakeMsg(clsAddressBook, 6) 

Arguments typedef struct ADDR_BOOK_ENUM_GROUP_MEMBER { 

ADDR_BOOK_KEY groupKey; 

ADDR_BOOK_KEY startKey; 

BOOLEAN recurse; 

ADDR_BOOK_ATTR_ID sort; 

U32 count; 

P_ADDR_BOOK_KEY pKeys; 

} ADDR_BOOK_ENUM_GROUP_MEMBER, *P_ADDR_BOOK_ENUM_GROUP_MEMBER; 

ConiineRfs Parameters: 

pArgs->groupKey In: key of the group 

pArgs->startKey In: where to start the group enumeration. Use pNull to start from the beginning. 
Out:last entry key returned in pArgs->pKeys. Client usually uses the out value to be the next in 
value of the next msgAddrBookEnumGroupMembers call. 

pArgs->recurse In: whether to recursively enumerate groups 
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pArgs->sort In: attr id of the field to sort the returned entry id by 

pArgs->count In: number of entries to return, which is also the number of slots in the pKeys array. Use 
AddrBookAll to get every member. In this case address book will allocate the necessary space, and 
the client should free the space. Out:number of entries actually returned 

pArgs->pKeys Out:keys of the members of pArgs->groupKey 

msgAddrBooklsAMemberOf 

Determines if an entry is a member of a group. 

Takes P_ADDR_BOOK_IS_A_MEMBER_OF, returns STATUS. 

tdefine msgAddrBooklsAMemberOf MakeMsg(clsAddressBook, 7) t 

Arguments typedef Struct ADDR_BOOK_IS_A_MEMBER_OF { 

ADDR_BOOK_KEY groupKey; Z 

ADDR_BOOK_KEY memberKey; § 

BOOLEAN recurse; " 

} ADDR_BOOK_IS_A_MEMBER_OF, *P_ADDR_BOOK_IS_A_MEMBER_OF; 

!ommepts Parameters: 

pArgs->groupKey In: key of the group 

pArgs->memberKey In: potential members key 

pArgs->recurse In: whether to recursively test for membership 
lefornVoioe stsOK if pArgs->memberKey is a member of pArgs->groupKey. 

stsNoMatch if pArgs->memberKey is not a member of pArgs->groupKey 

msgAddrBookGetMetrics 

Passes back the metrics for the address book. 

Takes P_ADDR_BOOK_METRICS, returns STATUS. 

tdefine msgAddrBookGetMetrics MakeMsg{clsAddressBook, 8) 

Arguments typedef Struct ADDR_BOOK_METRICS { 

U32 numEntries; // Total number of entries 

U32 numGroups; // Number of groups in the address book 

U16 numServices; // Number of known services 

U32 spare 1; 

U32 spare 2; 
} ADDR_BOOK_METRICS, *P_ADDR_BOOK_METRICS; 

msgAddrBookAddAttr 

Adds a new attribute to active address books. 

Takes P_ADDR_BOOK_ATTR, returns STATUS. 

tdefine msgAddrBookAddAttr MakeMsg(clsAddressBook, 12) 

Message typedef struct ADDR_BOOK_ATTR { 

Irgwmeiifs ADDR_BOOK_ATTR_ID id; 

ADDR_BOOK_ATTR_TYPE type; 

ADDR_BOOK_ATTR_LENGTH length; // length of value, in bytes 

ADDR_BOOK_ATTR_VALUE value; 

ADDR_BOOK_ATTR_LABEL label; // for display purpose 

} ADDR BOOK ATTR, *P ADDR BOOK ATTR; 
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This operation will change the address book database schema. If the attribute is of type abNumber, the 
value is initialized to be for all existing address book entries. If the attribute is of type 
abPhoneNumber, then the value is intialized to be 0. If the attribute is of type abString or abOther, the 
value is initialized to be length byte array. 

After an attribute is added to an address book, clients can then set the attribute value in subsequent 
msgAddrBookSet's and get the attribute value in the subsequent msgAddrBookGet's. Failure to first 
make an attribute knov/n to an address book and then try to set or get the attribute value will cause 
stsAddrBooklnvalidAttr to be returned. 

Parameters: 

pArgs->id In: the id(should be a tag) of the new attribute. It has to be different from all other attribute 
ids in the same address book. 

pArgs->type In: one of abNumber, abString, abOther, abPhoneNumber 

pArgs->label In; a string, for display purpose. The address book will copy the string to its own storage. 
stsRequestNotSupported if the address book does not allow dynamically changing its database schema. 
stsAddrBookDupIicateAttrld There is another attribute in the address book w/ the same id. 

msgAddrBookCount 

Finds the number of entries that match the search spec 

Takes P_ADDR_BOOK_COUNT, returns STATUS. 

#define msgAddrBookCount MakeMsg(clsAddressBook, 13) 

typedef struct ADDR_BOOK_COUNT { 

ADDR_BOOK_KEY key; 

ADDR_BOOK_ATTR_ID sort; 

ADDR_BOOK_SEARCH_DIR dir; 

ADDR_BOOK_QUERY query; 

Ul 6 count ; 

} ADDR_BOOK_COUNT, *P_ADDR_BOOK_COUNT ; 

Parameters: 

pArgs->key In where to stop counting, AddrBookAll to count the entire database 
pArgs->dir In whether to start counting from the beginning or the end of the address book. 
pArgs->query In qualifier. See msgAddrBookSearch 



Observer Messages 



msgAddrBookEntryChanged 

Sent to observers when an entry has been changed, added or deleted. 

Takes P_ADDR_BOOK_ENTRY_CHANGE, returns STATUS. 

#define msgAddrBookEntryChanged MakeMsg(clsAddressBook, 11) 
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Enuml 6 ( ADDR_BOOK_CHANGE_TYPE ) { 


abServiceChanged 


= 0, 


abServiceDeleted 


= 1, 


abServiceAdded 


= 2, 


abEntry Added 


= 3, 


abEntryDeleted 


= 4, 


abEnt ryNameChanged 


= 5, 


abEntry Changed 


= 6, 


abServicelnstalled 


= 7, / 


abServiceDeinstalled 


= 8, / 


1 1 

typedef struct ADDR BOOK ENTRY CHANGE 


OBJECT 


addrBook; 


ADDR_BOOK_CHANGE_TYPE 


type; 


ADDR_BOOK_KEY 


entry Key; 



// svcs have been installed 
// svcs have been deinstalled 

// Address book UID 
// Type of change 

// Internal address book key of the >. 

// changed entry ^ 

ADDR_BOOK_SERVICE_ID svcid; // service id, if applicable g 

} ADDR BOOK ENTRY CHANGE, *P ADDR BOOK ENTRY CHANGE; 5 

Z 

Comments If pArgs->type is abServiceChanged, abServiceDeleted, abServiceAdded, then the address book fills in 3 

pArgs->svcId to be the id of the service address affected. pArgs->entryKey is filled in by the address 
book except when pArgs->type is abServicelnstalled or abServiceDeinstalled. In that case, the address 
book is notifying clients that some service has been installed or deinstalled, and the service 
information returned by the previous msgAddrBookGetServiceDesc is no longer up-to-date. 
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ATALK.H 



This file contains the API for clsATP. 

clsATP inherits from clsObject. 

Provides remote access to stations using the AppleTalk protocol suite. 

tifndef ATALK_INCLUDED 
#define ATALK_INCLUDED 



Common #clefines and lypedefs 



* P DDP TYPE; 



{ 



typedef U8 DDP_TYPE, 
typedef U8 ATP_FLAGS; 
typedef struct ATP_ADDRESS 

U16 network; 

U8 node; 

US socket ; 
} ATP_ADDRESS, * P_ATP_ADDRESS; 

typedef struct USER_BYTES { 

U8 ubl; 

U8 ub2, 

US ub3, 

US ub4, 

} USER_BYTES, * P_USER_BYTES; 
typedef struct ATP_OPTIONS { 



DDP_TYPE 

ATP_FLAGS 

U16 

U32 
U16 
US 



ddpType; 

flags; 

transactionID; 

interval; 

retries; 

numUserByteSets; 



reserved; 
userBytes [ S ] ; 
* P ATP OPTIONS; 



99 



US 

USER_BYTES 
} ATP_OPTIONS, 

// ATP flags 
#define ATP_XO_Flag 
tdefine ATP_Checksum_Flag 
♦define ATP_ALONoResponse_Flag 
typedef US NBP_NAME, 

tdefine NBP_NAME_Size 

Format for an NBP name is: 

U8 objectNameLength; 

U8 objectName [ objectNameLength ] ; 

U8 typeNameLength; 

US typeName[ typeNameLength ] ; 

US zoneNameLength; 

US zoneName [ zoneNameLength ] ; 

typedef US NBP_ENUMERATOR; 



//In: transaction id when sending a response 

// Out: transaction id when receiving a request 

// timeout value in milliseconds 

// number of times to retry a request 

// In: number of valid user byte sets to send 

// Out: number of valid user byte sets received 



0x01 
0x02 
0x04 
P NBP NAME; 
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typedef struct NBP_TUPLE { 

ATP_ADDRESS address; 

NBP_ENUMERATOR enumerator; 

NBP_NAME name[ NBP_NAME_Size ]; 
} NBP_TUPLE, * P_NBP_TUPLE; 

typedef U8 ZONES_BUFFER, * P_ZONES_BUFFER; 



Messages 



msgNBPRegister 

Registers a name with the network. 

Takes P_NBP_REGISTER, returns STATUS. 

tdefine msgNBPRegister MakeMsg( clsATP, 1 ) 

typedef struct NBP_REGISTER { 

P_NBP_NAME pName; // name to register 
} NBP REGISTER, * P NBP REGISTER; 



msgNBPRemove 

Removes a previously registered name from the network. 

Takes P_NBP_REMOVE, returns STATUS. 

fdefine msgNBPRemove MakeMsg{ clsATP, 2 ) 

typedef struct NBP_REMOVE { 

P_NBP_NAME pName; // name to remove 

} NBP REMOVE, * P NBP REMOVE; 



msgNBPLookup 

Looks up names registered with the network. 

Takes P_NBP_LOOKUP, returns STATUS. 

tdefine msgNBPLookup MakeMsg( clsATP, 3 ) 

typedef struct NBP_LOOKUP { 

P_NBP_NAME pName; // name spec to lookup 

P_TP_BUFFER pBuffer; // ptr to buffer containing names found 

U16 length; // size of buffer in bytes 

U16 numMatches; // In-Out: number of names wanted/ found 

} NBP LOOKUP, * P NBP LOOKUP; 



msgNBPConfirm 

Confirms the network address of a registered name. 

Takes P_NBP_CONFIRM, returns STATUS. 

#define msgNBPConfirm MakeMsg( clsATP, 4 ) 

typedef struct NBP_CONFIRM { 

P_NBP_NAME pName; // name to confirm address of 

P_TP_ADDRESS pAddress; // ptr to address of name 

} NBP CONFIRM, * P NBP CONFIRM; 
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msgZIPGetZoneList 

Obtains a list of zone names. 

Takes P_ZIP_GETZONES, returns STATUS. 

#define msgZIPGetZoneList MakeMsg( clsATP, 6 ) 

typedef struct ZIP_GETZONES { 

P_ZONES_BUFFER pBuffer; // ptr to buffer to contain zone names 
U16 length; // size of buffer in bytes 

U16 numZones; // Out: number of zones found 

} ZIP GETZONES, * P ZIP GETZONES; 



>- 
I- 

> 

Obtains my zone name. y 

z 
z 
o 

u 

#define msgZIPGetMyZone MakeMsg ( clsATP, 7 ) 



msgZIPGetMyZone 

Obtains my zone name. 

Takes P_ZIP_GETZONES, returns STATUS. 



typedef struct ZIP_GETZONES { 

P_ZONES_BUFFER pBuffer; // ptr to buffer to contain zone names 
U16 length; // size of buffer in bytes 

U16 numZones; // Out: number of zones found 

} ZIP GETZONES, * P ZIP GETZONES; 



msgATPRespPktSize 

Sets the maximum size of ATP response packets. 

Takes P_ATP_RESPPKTSIZE, returns STATUS. 

#define msgATPRespPktSize MakeMsg ( clsATP, 8 ) 

typedef struct ATP_RESPPKTSIZE { 

U16 size; // max size of response packets in bytes 

} ATP RESPPKTSIZE, * P ATP RESPPKTSIZE; 
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CNCTIONS.H 



This file contains the API definition for the interface between the connections notebook and a generic 
service. 

The connections notebook is, effectivety^, an option sheet. Because of this implementation choice, it is 
important to understand the option sheet protocol and messages, as defined in OPTION.H. The 
terminology chosen herein reflects the close association between the connections notebook and an 
option sheet. 

The two default views that one gets, for disks and printers, in the connections notebook are each option 
sheets added as cards of the connections notebook option sheet. Other sheets or windows can be added 
to the connections notebook. 

The connections notebook observes the well-known list theConnections. If an item is added to the list, 
the connections notebook calls that item with msgConnectionsAddSheet, with the P_ARGS being the 
main option sheet in the connections notebook. By using msgOptionAddCard to the object passed in 
the aforementioned call, a service can add a sheet or just a single window to the connections notebook. 
Once these items have been added, all responsibility for the user interface and fiinctionality rests solely 
on the service. 

Network disks and printers, however, are handled differently. There are already predefined windows for 
these two items. A network file-sharing system, for example, would add itself to the well-known list 
theVolumeServices. The connections notebook, which observes this list, would send the object on the 
list a msgConnectionsStartConversation and a msgConnectionsSetConnectionsApp to pass along the 
application context of the connections notebook from this time. 

If the network file-sharing service were to remove itself from theVolumeServices, the connections 
notebook would send msgConnectionsEndConveration to the object. 

The object on the list is expected to be able to respond to the various connections messages. If it has 
specified that it provides a UI, it will be asked for its network view when appropriate. 

#ifndef CNCTIONS_INCLUDED 
♦define CNCTIONS_INCLUDED 

tifndef INSTLMGR_INCLUDED 
tinclude <instlmgr.h> 
tendif 



Common #defines and typedefs 



Warnings 



♦define stsConnectionsAlreadyConnected 



MakeWarning{clsConnections, 1) 



Statuses 



♦define stsConnectionsPasswordFailed 
♦define stsConnectionsServiceDeinstalling 
♦define stsConnectionsNotConnected 



MakeStatus (clsConnections, 1) 
MakeStatus (clsConnections , 2 ) 
MakeStatus (clsConnections, 3) 
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Typedefs 



typedef struct CONNECTIONS_MENU_ITEM { 

P_CHAR pName; 

OBJECT net Service; 

P_UNKNOWN netldentifier; 

U32 reserved [2]; 

} CONNECT IONS_MENU_ITEM, * P_CONNECTIONS_MENU_ITEM; 

typedef struct CONNECTIONS_ITEM { 

struct CONNECTIONS ITEM *pNextConnectionsItem; 



// Next item 



P_UNKNOWN 

TAG 

TAG 

P_CHAR 

P_CHAR 

P_CHAR 

P_CHAR 

BOOLEAN 

BOOLEAN 

BOOLEAN 



pItemID; // Service defined identifer 

// for this item 

itemlconTag; // Item' s icon tag 

itemTag; // Item tag 

name; // Item name 

serverName; // Item's server's name 

location; // Item' s location 

type; // Item's type 

connected; // Connected? 

autoConnect; // Auto-connect enabled? 

remember; // Remember (menu) enabled? 



// fill in some more information here 

P_UNKNOWN itemSpecificData; // volume or printer stuff 

U32 filler [4]; // reserved 

} CONNECTIONS ITEM, * P CONNECTIONS ITEM, * * PP CONNECTIONS ITEM; 



Messages 



tnsgConnectionsSetState: 

Sets the specified states in the service. 

Takes P_CONNECTIONS_STATE, returns STATUS. 



Enumie ( CONNECTIONS_CONNECT_STATE 
cnctManualConnect ions , 
cnctAutoConnections, 
cnctPromiscuousConnections 



) { 



}; 



) { 



Enumie ( CONNECTIONS_WARNINGS 

cnctWarningNone 

cnctWarningPermissionsFailure 

cnctWarningOnConnection 

cnctWarningOnUnconnection 
}; 
Enumie ( CONNECTIONS_PASSWORDS ) { 

cnctPasswordNone 

cnctPasswordServer 

cnctPasswordltem 

cnctPasswordServerAndltem 



}; 



) { 



{ 



Enumie ( CONNECTIONS_PERMISSIONS 

cnctPermissionsReadWrite, 

cnctPermissionsReadOnly 
}; 
typedef struct CONNECTIONS_STATE 

BOOLEAN 

CONNECT IONS_CONNECT_STATE 

CONNECTIONS_WARNINGS 

CONNECTIONS_PASSWORDS 

CONNECTIONS_PERMISSIONS 

U32 
} CONNECTIONS_STATE, * P_CONNECTIONS 

tdefine msgConnectionsSetState 



// Connect only when asked to 
// Connect auto-connect items 
// Connect to everything 



0, //No warnings 

flagO, // On permissions failure 

flagl, // On connection 

flag2 // On loss of connection 



0, //Do not save passwords 
flagO, // Save server passwords 
flagl, // Save item passwords 
flag2 // Save server and item 
// passwords 



// Connect Read/Write 
// Connect Read only 



attached; // 

connectMores; // 

connectWarning; // 

connectPasswords; // 

connectPermissions; // 
reserved [4] ; 
STATE; 

MakeMsg ( clsConnections, 1 



Attached 
How to attach 
Level of warnings 
What passwords 
What permissions 
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msgConnectionsGetState: 

Gets the specified states in the service. 

Takes P_CONNECTIONS_STATE, returns STATUS. 

tdefine msgConnectionsGetState 



MakeMsg ( clsConnections, 2 ) 



typedef struct CONNECTIONS_STATE { 
BOOLEAN 

CONNECTIONS_CONNECT_STATE 
CONNECTIONS_WARNINGS 
CONNECTIONS_PASSWORDS 
CONNECTIONS_PERMISSIONS 
U32 



attached; 
connectMores; 
connectWarning; 
connectPasswords ; 



// Attached 

// How to attach 

// Level of warnings 

// What passwords 



connectPermissions; // What permissions 
reserved [4] ; 



} CONNECTIONS STATE, * P CONNECTIONS STATE; 



msgConnectionsEnutnerateltems: 

Gets a list of the networlc items, per restrictions. 
Takes P_CONNECTIONS_ENUMERATE, returns STATUS. 



#define cnctAttribMatchLocation flagO 

tdefine cnctAttribMatchServer flagl 

#define cnctAttribMatchConnect flag2 

#define cnctAttribMatchAutoConnect flagS 

tdefine cnctAttribMatchMenu flag4 



// Match on location 

// Match on server 

// Match on connected state 

// Match on auto-connect state 

// Match on menu 

// (remember) state 



typedef struct ATTRIB { 
U32 flags; 



P CHAR 



restrictName; 



// various meanings -- complete match 
// match at beginning, match at end 

// connected, auto connect, remember 

// match this string 



// other possible characteristics — type, characteristics, etc. 



P UNKNOWN 



matchID; 



TAG tag; 

} ATTRIB, * P_ATTRIB; 

fdefine cnctFlagLocationsOnly 

#define cnctFlagServersOnly 

tdefine cnctFlagOKFreeCIFields 

tdefine cnctFlagOKFreeCI 

typedef struct CONNECT IONS_ENUMERATE { 

attributes; 

count; //in 



// restrict enumeration to this file 

// server 

// Tag to match against 

flagO // Look only at locations 

flagl // Look only at servers 

flagl4 // Free the CI fields 

flagl5 // Free the CI 



ATTRIB 
U16 

U16 



P CONNECTIONS ITEM 



U16 



next ; 

pEntry; 
flags ; 



// out 

// in 
// 
// 

// in 

// out 

// in 

// out 



= t of entries to return in list. 
= t of valid entries in list. 
= to start at beginning 

OR previous out value to pick up 

where we left off. 
= pNull. 

= Link list of connections items. 
= state flags to filter on. 
= free state 



} CONNECT IONS_ENUMERATE, * P_CONNECTIONS_ENUMERATE; 

tdefine msgConnectionsEnumerateltems MakeMsg ( clsConnections, 3 ) 



msgConnectionsEnumerateServers: 

Gets a list of the network servers, per restrictions. 

Takes P_CONNECTIONS_ENUMERATE, returns STATUS. 

tdefine msgConnectionsEnumerateServers MakeMsg ( clsConnections, 4 ) 



372 PENPOINT API REFERENCE 

Part 10 / Connectivity 

isge typedef struct CONNECTIONS_ENUMERATE \ 

iments ATTRIB attributes; 

U16 count; //in 



U16 



P CONNECTIONS ITEM 



// out 
next; //in 
// 
// 
pEntry; //in 
// out 
U16 flags; //in 

// out 
} CONNECTIONS_ENUMERATE, * P_CONNECTIONS_ENUMERATE; 

Use CONNECTIONSJTEM with restriction of cnctFlagServersOnly. 



= # of entries to return in list. 
= # of valid entries in list. 
= to start at beginning 

OR previous out value to pick up 

where we left off. 
= pNull. 

= Link list of connections items. 
= state flags to filter on. 
= free state 



msgConnectionsEnumerateTags: 

Gets a list of tiie known tags, per restrictions. 

Takes P_CONNECTIONS_ENUMERATE, returns STATUS. 

typedef struct CONNECTIONS_TAG { 

TAG tag; 
} CONNECTIONS_TAG, * P_CONNECTIONS_TAG; 
tdefine msgConnectionsEnumerateTags 



typedef struct CONNECTIONS ENUMERATE { 



ATTRIB 


attributes; 


U16 


count ; 


// in 
// out 


U16 


next ; 


// in 

// 

// 


P_CONNECTIONS_ITEM 


pEntry; 


// in 
// out 


U16 


flags ; 


// in 
// out 



MakeMsg ( clsConnections, 5 ) 



= # of entries to return in list . 
= # of valid entries in list. 
= to start at beginning 

OR previous out value to pick up 

where we left off. 
= pNull. 

= Link list of connections items. 
= state flags to filter on. 
= free state 



} CONNECTIONS ENUMERATE, * P CONNECTIONS ENUMERATE; 



msgConnectionsGetNetworkView: 

Each service is required to provide a window, which will be a client of a scrollwin, which will be set as 
the current (active) window when the network view is invoked. This window will be able to make use of 
msgConnections calls to manipulate attachments, et al. 

Takes P_WIN, returns STATUS. 

tdefine msgConnectionsGetNetworkView MakeMsg ( clsConnections, 6 ) 



msgConnectionsCompareltems: 

Compares two pltemlD values to see if they refer to the same item. 
Takes P_CONNECTIONS_COMPARE, returns STATUS. 
typedef struct CONNECTIONS COMPARE { 



P_UNKNOWN 


iteml; 


// First item 


P UNKNOWN 


item2; 


// Second item 


BOOLEAN 


same; 


// Out: Are they the same? 


U32 


forPublicUse; 


// if any one needs this 



} CONNECT IONS_COMP ARE, * P_CONNECTIONS_COMPARE; 

tdefine msgConnectionsCompareltems MakeMsg ( clsConnections, 10 ) 
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msgConnectionsTagltetn: 

Tags the indicated item. 

Takes P_CONNECTIONS_TAG_ITEM, returns STATUS. 

typedef struct CONNECTIONS TAG ITEM { 



TAG 


tag; 


// Tag to set 


U32 


flags; 


// Type 


P UNKNOWN 


net Address; 


// Item' s address 


U32 


userlnformation; 





} CONNECTIONS_TAG_ITEM, * P_CONNECTIONS_TAG_ITEM; 

tdefine msgConnectionsTagltem MakeMsg ( clsConnections, 11 ) 



msgConnectionsGetServicelnfo: g 

Gets the service name and other information. z 

z 

Takes P_CONNECTIONS_SERVICE_INFO, returns STATUS. 8 

irgyrnenfs typedef Struct CONNECTIONS_SERVICE_INFO { 

CHAR serviceName[nameBufLength] ; // Service name 

U16 reserved: 15, 

uiProvided:l; // User interface provided 

U32 filler [2]; 

} CONNECTIONS_SERVICE_INFO, * P_CONNECTIONS_SERVICE_INFO; 
♦define msgConnectionsGetServicelnfo MakeMsg ( clsConnections, 12 ) 

msgConnectionsGetltetnlnfo: 

Gets information for the specified item, specific to the service. 

Takes P_UNKNOWN, returns STATUS. 

#define msgConnectionsGetltemlnfo MakeMsg ( clsConnections, 13 ) 



msgConnectionsSetConnectionsApp: 

Passes the connections notebook app object to the service. 

Takes OBJECT, returns STATUS. 

Idefine msgConnectionsSetConnectionsApp MakeMsg ( clsConnections, 14 ) 

msgConnectionsUpdate: 

Requests an update of the current network state. 

Takes nothing, returns STATUS. 

Idefine msgConnectionsUpdate MakeMsg ( clsConnections, 15 ) 

msgConnectionsExpandCoUapse: 

Requests an expand/collapse (depending on the argument) of the current view of the network. 

Takes BOOLEAN, returns STATUS. 

Idefine msgConnectionsExpandCoUapse MakeMsg ( clsConnections, 16 ) 
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msgConnectionsConnectltem: 

Connect the specified item. 

Takes P_CONNECTIONS_REQUEST, returns STATUS. 

Argyiiienfs typedef struct CONNECTIONS_REQUEST { 

P_UNKNOWN pItemID; // Item to connect 

U32 response; 

} CONNECT IONS_REQUEST, * P_CONNECTIONS_REQUEST; 

#define msgConnectionsConnectltem MakeMsg ( clsConnections, 17 ) 



msgConnectionsUnconnectltem: 

Unconnect the specified item. 

Takes P_CONNECTIONS_REQUEST, returns STATUS. 

fdefine msgConnectionsUnconnectltem MakeMsg ( clsConnections, 18 ) 

^lessoge typedef struct CONNECTIONS_REQUEST { 

Arguriieiits P_UNKNOWN pItemID; // Item to connect 

U32 response; 

} CONNECTIONS REQUEST, * P CONNECTIONS REQUEST; 



msgConnectionsRememberltem: 

Remember the specified item. 

Takes P_CONNECTIONS_REQUEST, returns STATUS. 

#define msgConnectionsRememberltem MakeMsg ( clsConnections, 19 ) 

typedef struct CONNECTIONS_REQUEST { 

P_UNKNOWN pItemID; // Item to connect 

U32 response; 

} CONNECTIONS REQUEST, * P CONNECTIONS REQUEST; 



msgConnectionsForgetltem: 

Forget the specified item. 

Takes P_CONNECTIONS_REQUEST, returns STATUS. 

♦define msgConnectionsForgetltem MakeMsg ( clsConnections, 20 ) 

typedef struct CONNECTIONS_REQUEST { 

P_UNKNOWN pItemID; // Item to connect 

U32 response; 

} CONNECTIONS_REQUEST, * P_CONNECTIONS_REQUEST; 

msgConnectionsAutoConnectltem: 

Sets the auto connect state on for the specified item. 
Takes P_CONNECTIONS_REQUEST, returns STATUS. 
fdefine msgConnectionsAutoConnectltem MakeMsg ( clsConnections, 21 ) 

typedef struct CONNECTIONS_REQUEST { 

P_UNKNOWN pItemID; // Item to connect 

U32 response; 

} CONNECTIONS REQUEST, * P CONNECTIONS REQUEST; 



CNCTIONS.H 375 

Common #defines and typedefs 

msgConnectionsUnAutoConnectltem: 

Sets the auto connect state off for the specified item. 
Takes P_CONNECTIONS_REQUEST, returns STATUS. 
tdefine msgConnectionsUnAutoConnectltem MakeMsg { clsConnections, 22 ) 

typedef struct CONNECTIONS_REQUEST { 

P_UNKNOWN pItemID; // Item to connect 

U32 response; 

} CONNECTIONS_REQUEST, * P_CONNECTIONS REQUEST; 

msgConnectionsAddSheet: >_ 

Permits items on the connections to add items to the contents. ^ 

u 
Takes OBJECT, returns STATUS. Z 

#define msgConnectionsAddSheet MakeMsg ( clsConnections, 23 ) 8 

msgConnectionsAddCards: 

Sent to network views, when they are not the foremost view, to run the option protocol. 

Takes P_OPTION_TAG, returns STATUS. 

#define msgConnectionsAddCards MakeMsg { clsConnections, 24 ) 

msgConnectionsSetSelection: 

Sent by the connections notebook to the appropriate service, informing the service what the currently 
selected item is. 

Takes P_UNKNOWN, returns STATUS. 

tdefine msgConnectionsSetSelection MakeMsg ( clsConnections, 25 ) 



msgConnectionsGeCTopCard: 

Sent by the connections notebook to the appropriate service, inquiring of that service what the 
appropriate top card is to be. 

Takes P_TAG, returns STATUS. 

#define msgConnectionsGetTopCard MakeMsg { clsConnections, 26 ) 

msgConnectionsStartConversation: 

Sent by the Connections Notebook to the appropriate service, informing that service that the 
Connections Notebook is planning on conversing with it. This message will be sent at first page turn 
and at restore (of the Connections Notebook) time. 

Takes nothing, returns STATUS. 

#define msgConnectionsStartConversation MakeMsg { clsConnections, 27 ) 



376 PENPOINT API REFERENCE 

Part 10 / Connectivity 



msgConnectionsEndConversation: 

Sent by the Connections Notebook to the appropriate service, informing that service that the 
Connections Notebook is stopping conversing with it. This message will be sent at save (of the 
Connections Notebook) time. 

Takes nothing, returns STATUS. 

tdefine msgConnectionsEndConversation MakeMsg ( clsConnections, 28 ) 

msgConnectionsIsParent: 

Compares two pItemID values to see if item 1 is a parent of item2. 

Takes P_CONNECTIONS_COMPARE, returns STATUS. 

tdefine msgConnectionsIsParent MakeMsg ( clsConnections, 31 ) 

typedef struct CONNECTIONS COMPARE { 



P UNKNOWN 


iteml; 


// First item 


P UNKNOWN 


item2; 


// Second item 


BOOLEAN 


same; 


// Out: Are they the same? 


U32 


forPublicUse; 


//if any one needs this 



} CONNECT IONS_COMP ARE, * P_CONNECTIONS_COMPARE; 

Notification Messages 

msgConnectionsConnectedChanged: 

Sent by the appropriate service, indicating when an item has been connected to or unconnected from. 

Takes P_CONNECTIONS_NOTIFY, returns STATUS. 

#define msgConnectionsConnectedChanged MakeMsg ( clsConnections, 7 ) 

typedef struct CONNECTIONS_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HANDLE handle; // handle to service 

OBJECT service; // service that sent notification 

P_UNKNOWN pItemID; // pointer to affected item 
U16 reserved: 13, 

server:!, // Unused 

uiProvided:l, // Unused 

state :1; // connected or unconnected 

U16 notifyLength; // Length of notify info which follows 

} CONNECTIONS NOTIFY, * P CONNECTIONS NOTIFY; 



msgConnectionsAutoConnectChanged: 

Sent by the appropriate service, indicating when an item has had the auto connect state set or turned off 
for it. 

Takes P_CONNECTIONS_NOTIFY, returns STATUS. 

tdefine msgConnectionsAutoConnectChanged MakeMsg ( clsConnections, 8 ) 

Messoge typedef struct CONNECT IONS_NOTIFY { 

Arguments OBJECT manager; // manager that sent notification 

IM_HANDLE handle; // handle to service 

OBJECT service; // service that sent notification 

P_UNKNOWN pItemID; // pointer to affected item 
U16 reserved: 13, 

server:!, // Unused 

uiProvided:l, // Unused 

state :1; // connected or unconnected 

U16 notifyLength; // Length of notify info which follows 

} CONNECTIONS NOTIFY, * P CONNECTIONS NOTIFY; 



Message 
Arguments 
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msgConnectionsRememberChanged: 

Sent by the appropriate service, indicating when an item has had the remember state set or turned off 
for it. 



Takes P_CONNECTIONS_NOTIFY, returns STATUS. 
#define msgConnectionsRememberChanged 



MakeMsg ( clsConnections, 9 ) 



typedef struct CONNECTIONS_NOTIFY { 

OBJECT manager; 

IM_HANDLE handle; 

OBJECT service; 

P_UNKNOWN pItemID; 

U16 reserved: 13, 

server :1, 
uiProvided:l, 
state : 1 ; 

U16 notifyLength; 



// manager that sent notification 

// handle to service 

// service that sent notification 

// pointer to affected item 

// Unused 

// Unused 

// connected or unconnected 

// Length of notify info which follows 



} CONNECTIONS NOTIFY, * P CONNECTIONS NOTIFY; 



Arqymenfs 



msgConnectionsItemChanged: 

Sent by the appropriate service, indicating when an item has been noticed or lost. 

Takes P_CONNECTIONS_NOTIFY, returns STATUS. 

tdefine msgConnectionsItemChanged MakeMsg ( clsConnections, 30 ) 



typedef struct CONNECTIONS NOTIFY { 



OBJECT 

IM_HANDLE 

OBJECT 

P_UNKNOWN 

U16 



U16 
} CONNECTIONS NOTIFY, 



manager; 
handle ; 
service; 
pItemID; 
reserved: 13, 
server: 1, 
uiProvided:l, 
state :1; 
notifyLength; 
P CONNECTIONS 



// manager that sent notification 
// handle to service 
// service that sent notification 
// pointer to affected item 

// Unused 
// Unused 

// connected or unconnected 
// Length of notify info which follows 
NOTIFY; 



msgConnectionsServiceChanged: 

Sent by the appropriate service, indicating when it is available for use or unavailable. 

Takes P_CONNECTIONS_NOTIFY, returns STATUS. 

tdefine msgConnectionsServiceChanged MakeMsg ( clsConnections, 32 ) 



typedef struct CONNECT IONS_NOT IF Y { 



OBJECT 


manager; 


IM_HANDLE 


handle; 


OBJECT 


service; 


P UNKNOWN 


pItemID; 


U16 


reserved: 13, 




server :1, 




uiProvided:l, 




state: 1; 


U16 


notifyLength; 


} CONNECTIONS_NOTIFY, 


* P CONNECTIONS 



// manager that sent notification 
// handle to service 
// service that sent notification 
// pointer to affected item 

// Unused 
// Unused 

// connected or unconnected 
// Length of notify info which follows 
NOTIFY; 



.^ 
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DIALENV.H 



This file contains the API for clsDialEnv, clsDialEnvOptCard, and clsDialEnvField. 

clsDialEnv inherits from clsService. 

clsDialEnv maintains telephone dialing related information pertinent to a specific geographic 
location/environment. 

The intent of clsDialEnv is to relieve client data communication programs of having to replicate the 
code for maintaining their own seperate telephone dialing-related data and logic. clsDialEnv is designed 
to provide the "intelligence" and data needed for dialing from/to a variety of environments (to/from 
local in-house to/from international). 



clsDialEnvOptCard inherits from clsCustomLayout. 

clsDialEnvOptCard provides a default behavior of observing the dialing environment and refreshing 
dialing environment option cards when the dialing environment changes. 

cIsDialEnvField inherits from clsField. 

clsDialEnvField alters the a default behavior of ancestor clsField by specifying a character list template 
for coercing its field input. 

Dialing environments are a location type service and therefore managed by a service manager called 
theLocations. Each instance of a dialing environment is identified by the name of a location to which 
the dialing environment pertains (NOTE: for PenPoint 1.0 there is only a single location/dialing 
environment). Objects wishing to communicate with a dialing environment do so by sending messages 
to the current location service. The UID of the current location is obtained by querying theLocations 
via standard install manager and service manager messages. The following block of code provides one 
example of how a client might obtain dialing environment data. 



OBJECT handleCurrentLoc, 

theCurrentLocation; 
SM_QUERY_LOCK lock; 
SM_QUERY_UNLOCK unlock; 
DIALENV_COUNTRY country; 
IM_GET_SET_NAME getName; 
CHAR locationName [nameBufLength] ; 

// 

// 

// 

// 

// 

// 

// 

// 

// 

ObjCallJmp{msgIMGetCurrent, theLocations, &handleCurrentLoc, s, Problem); 

lock. handle = unlock . handle = handleCurrentLoc; 



Get the handle and UID of the current location. 

Lock the current location to guarantee exclusive access to 

location data. 
Get the country code for the current location (from the dialing 

environment for the current location) . 
Unlock the current location so that other clients may access it. 
Get the name of the current location. 
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ObjCallJmp(msgSMQueryLock, theLocations, &lock, s, Problem); 
theCurrentLocation = lock. service , • 

ObjCallJmp(msgDialEnvGetCountry, theCurrentLocation, &country, s, Problem); 
Ob jectCall (msgSMQueryUnlock, theLocations, &unlock) ; 
getName . handle = handleCurrentLoc; 
get Name . pName = locationName; 

ObjCallJmp(msgIMGetName, theLocations, SgetName, s. Problem); 
} 

For PenPoint 1.0 an application or service requiring dialing environment services should install the 

dialing environment dll via a SERVICE.INI file. 

**** Future Direction Ideas **** 

In a fixture release of PenPoint, dialing environments will be subsumed by a location service. The 
location service will manage all of the objects which provide location-dependent behavior to the 
PenPoint environment/applications. Current plans are for the user to access location services via the 
configuration notebook. Because dialing environments will be a constituent of a location service it won't 
be necessary for a dialing environment to be included by an application's or service's SERVICE.INI file. 

The location service will maintain the list of locations the user has created (GO may ship pre-configured 
locations; however a user will be able to create and modify locations). A user will select a location by 
name, and all of the unique properties regarding that location will take efi^ect. 

For each location there may be a dialing environment. Thus, whenever the user selects a new location, a 
different dialing environment may take effect (it is possible that two different locations will share the 
same dialing environment, or that a location doesn't have a dialing environment). When a user creates a 
new location, the user will be given the opportunity to specify a dialing environment for the new 
location, or to select one of the currently available dialing environments and bind it to the new location. 

The dialing environment will be enhanced to provide clients with information regarding valid city/area 
codes and dialing rules for specific countries. This information can be presented to the user for UI 
pick-lists, used to coerce input to only valid combinations of codes, and to enforce the rules which 
national telephone systems impose on computer sofiw^are which interacts with the public telephone 
system. 

**** End of Future Direction Ideas **** 

cIsDialEnvOptCard provides a default behavior of observing the dialing environment and refreshing 
dialing environment option cards when the dialing environment changes. A client needn't provide any 
special code support to have such option cards track dialing environment changes. Note: A client 
shouldn't insert a dialing environment option card into an option sheet or any window tree with a 
modal filter (e.g. option sheet with a style modality set to either osModalApp or osModalSystem). 

The following block of code provides one example of creating a dialing environment option card. 

{ 

// 

// Create an option card for dialing environment settings. 

// 

STATUS s; 

DIALENV_OPTCARD_NEW don; 

OBJECT handleCurrentLoc; 

IM_GET_SET_NAME getName; 

CHAR locationName [nameBuf Length] ; 
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// 

// Get the handle and name of the current location. Create 

// a dialing environment option card for the current location. 

// 

ObjCallRet (msglMGetCurrent, theLocations, ShandleCurrentLoc, s); 

getName . handle = handleCurrentLoc; 

getName . pName = locationName; 

ObjCallRet (msglMGetName, theLocations, SgetName, s) ; 

ObjCallRet (msgNewDefaults, clsDialEnvOptCard, &don, s) ; 

don. win. tag = tagDialEnvOptionCard; 

strcpy (don . dialenvOpt Card. dialEnv. name, locationName) ; 

ObjCallRet (msgNew, clsDialEnvOptCard, &don, s) ; 
} 
clsDialEnvField alters the a default behavior of ancestor clsField by specifying a character list template ^ 

for coercing its field input. > 

Defined within this header file. g 

z 
defines and typedefs for dial environment data, fijnction prototypes, messages & status values. O 

#ifndef DIALENV_INCLUDED 
♦define DIALENV_INCLUDED 

#ifndef GO_INCLUDED 

tinclude <go.h> 

tendif 

#ifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef SERVICE_INCLUDED 

tinclude <service.h> 

#endif 

#ifndef CLAYOUT_INCLUDED 

#include <clayout.h> 

#endif 

tifndef FIELD_INCLUDED 

tinclude <field.h> 

tendif 



Defines and typedefs 

Class UIDs for: 



clsDialEnv The dialing environment service. 
clsDialEnvOptCard Dialing environment option cards. 
clsDialEnvField Field for entering and coercing dialing codes/numbers. 
theLocations Service manager for dialing environments. 

tdefine clsDialEnv MakeWKN(2576,l,wknGlobal) 

tdefine clsDialEnvOptCard MakeWKN(2577, 1, wknGlobal) 

tdefine clsDialEnvField MakeWKN (2578, 1, wknGlobal) 

tdefine theLocations MakeWKN (2579, 1, wknGlobal) 

Dialing Environment Quick Help. 

♦ Quick help is stored in clsDialEnv resource list 0. 

♦ Each quick help entry is located by its index/positionwithin resource list 0. 

tdefine resListDialEnvQHelp 

tdefine MakeDialEnvQHelpResId(x) MakelndexedResId (clsDialEnv, resListDialEnvQHelp, x) 

tdefine tagDialEnvOptCard MakeTag (clsDialEnv, 1) 

tdefine hlpDialEnvOptCard MakeDialEnvQHelpResId(O) 

tdefine tagDialEnvDialEnvTable MakeTag (clsDialEnv, 17) 

tdefine hlpDialEnvDialEnv MakeDialEnvQHelpResId(O) 
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tdefine tagDialEnvCurrentLocLabel 
#define tagDialEnvCurrentLocTable 
#define hlpDialEnvCurrentLoc 

tdefine tagDialEnvDialLabel 
#define tagDialEnvDial 
#define tagDialEnvDialTone 
tdefine tagDialEnvDialPulse 
tdefine hlpDialEnvDial 

tdefine tagDialEnvAreaCityLabel 
tdefine tagDialEnvAreaCity 
tdefine hlpDialEnvAreaCity 

tdefine tagDialEnvCountryLabel 
tdefine tagDialEnvCountry 
tdefine hlpDialEnvCountry 

tdefine tagDialEnvOutsideLineLabel 
tdefine tagDialEnvOut sideline 
tdefine hlpDialEnvOutsideLine 

tdefine tagDialEnvLongDistLabel 
tdefine tagDialEnvLongDist 
tdefine hlpDialEnvLongDist 
tdefine tagDialEnvIntlAccessLabel 
tdefine tagDialEnvIntlAccess 
tdefine hlpDialEnvIntlAccess 

tdefine tagDialEnvSuffixLabel 
tdefine tagDialEnvSuffix 
tdefine hlpDialEnvSuffix 

tdefine tagDialEnvMacroCodesLabel 
tdefine tagDialEnvMacroCodes 
tdefine hlpDialEnvMacroCodes 
tdefine tagDialEnvSetCodes 
tdefine tagDialEnvMacroCodeALabel 
tdefine tagDialEnvMacroCodeA 
tdefine tagDialEnvMacroCodeBLabel 
tdefine tagDialEnvMacroCodeB 
tdefine tagDialEnvMacroCodeCLabel 
tdefine tagDialEnvMacroCodeC 
tdefine tagDialEnvMacroCodeDLabel 
tdefine tagDialEnvMacroCodeD 
tdefine tagDialEnvMacroCodesFrame 
tdefine deMaxMacroCodes 



MakeTag(clsDialEnv, 18) 
MakeTag(clsDialEnv, 19) 
MakeDialEnvQHelpResId(6) 

MakeTag(clsDialEnv, 24) 
MakeTag(clsDialEnv, 25) 
MakeTag(clsDialEnv, 26) 
MakeTag{clsDialEnv, 27) 
MakeDialEnvQHelpResId (7) 

MakeTag(clsDialEnv, 32) 
MakeTag{clsDialEnv, 33) 
MakeDialEnvQHelpResId (9) 
MakeTag{clsDialEnv, 40) 
MakeTag(clsDialEnv, 41) 
MakeDialEnvQHelpResId (8) 
MakeTag(clsDialEnv, 48) 
MakeTag(clsDialEnv, 49) 
MakeDialEnvQHelpResId (1) 
MakeTag(clsDialEnv, 56) 
MakeTag(clsDialEnv, 57) 
MakeDialEnvQHelpResId (2) 
MakeTag(clsDialEnv, 64) 
MakeTag(clsDialEnv, 65) 
MakeDialEnvQHelpRes Id ( 3 ) 
MakeTag(clsDialEnv, 72) 
MakeTag(clsDialEnv, 73) 
MakeDialEnvQHelpResId (4 ) 

MakeTag(clsDialEnv, 80) 

MakeTag(clsDialEnv, 81) 
MakeDialEnvQHelpResId (5) 

MakeTag(clsDialEnv, 82) 

MakeTag(clsDialEnv, 83) 

MakeTag{clsDialEnv, 84) 

MakeTag(clsDialEnv, 85) 

MakeTag(clsDialEnv, 86) 

MakeTag(clsDialEnv, 87) 

MakeTag(clsDialEnv, 88) 

MakeTag(clsDialEnv, 89) 

MakeTag(clsDialEnv, 90) 

MakeTag(clsDialEnv, 91) 
4 



Exported function prototypes from dialenv.dll 

None currently defined. 

Message definitions 

NOTE msg #1 is reserved for private use. 



Observer Nofificafion Messages 



msgDialEnvChanged 

Notification sent to observers to indicate a dialing environment change. 

Takes OBJECT, returns STATUS. Category: observer notification. 

tdefine msgDialEnvChanged MakeMsg(clsDialEnv, 2) 
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Action Messages 

Comments The pArgs indicates the object which initiated the change to the dialing environment. pArgs of objNull 

indicates that the dialing environment is being destroyed. 

Observers which receive this message should refresh any local dialing environment information or view 
of such information. 

Error Return Values: N/A. 

^Action Messages 

msgDialEnvGetCountry 

Passes back the country code from the current dialing environment. 

Takes P_DIALENV_COUNTRY, returns STATUS. Category: service action request. 



tdefine msgDialEnvGetCountry MakeMsg(clsDialEnv, 3) Z 



ArgumenU typedef Struct DIALENV_COUNTRY 

{ 

CHAR symbols [lenDialEnvCountry+1] ; 
} DIALENV_COUNTRY, *P_DIALENV_COUNTRY; 

Comments Error Return Values: none, always returns stsOK. 



msgDialEnvIsCountryNorthAmerican 

Indicates whether or not the specified country code is North American. 

Takes P_DIALENV_COUNTRY, returns STATUS. Category: service action request. 

tdefine msgDialEnvIsCountryNorthAmerican MakeMsg(clsDialEnv, 6) 

message typedef struct DIALENV_COUNTRY 

Argyments { 

CHAR symbols [ lenDialEnvCount ry+1 ] ; 
} DIALENV_COUNTRY, *P_DIALENV_COUNTRY; 

Comments NOTES: This message is provided so a client may alter its UI and/or enforce editing rules unique to 

North American phone numbers. 

Returns stsOK if the specified country is North American, otherwise stsDialEnvNoMatch. 

msgDialEnvGetEnvironment 

Passes back the current dialing environment settings. 

Takes P_DIALENV_ENVIRONMENT, returns STATUS. Category: service action request. 

♦define msgDialEnvGetEnvironment MakeMsg(clsDialEnv, 4) 

typedef TAG DIALENV_DIAL_MODE; 

tdefine deTone tagDialEnvDialTone // Touch tone dialing, 

tdefine dePulse tagDialEnvDialPulse // Pulse code dialing. 

ArgwmeHfs typedef Struct DIALENV_OUTSIDE_LINE 

{ 

CHAR symbols [ lenDialEnvOut sideLine+1 ] ; 
} DIALENV_OUTSIDE_LINE, *P_DIALENV_OUTSIDE_LINE; 
typedef struct DIALENV_AREA_CITY 
{ 

CHAR symbols [lenDialEnvAreaCity+1] ; 
} DIALENV AREA CITY, *P DIALENV AREA CITY, **PP DIALENV AREA CITY; 
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typedef struct DIALENV_INTL_ACCESS 
{ 

CHAR symbols [lenDialEnvIntlAccess+1] ; 
} DIALENV_INTL_ACCESS, *P_DIALENV_INTL_ACCESS; 

typedef struct DIALENV_LONG_DIST 
{ 

CHAR symbols [lenDialEnvLongDist+1] ; 
} DIALENV_LONG_DIST, *P_DIALENV_LONG_DIST; 

Symbols appended to a dialing string. Typicallyfor credit card billing/call accounting purposes. 

typedef struct DIALENV_SUFFIX 
{ 

CHAR symbols [lenDialEnvSuff ix+1] ; 
} DIALENV_SUFFIX, *P_DIALENV_SUFFIX; 

Multi-purpose codes for specifying credit card #s, accountbilling codes, or altering environment 
dependent behavior. When a client requests to build a dial string, the symbols from a macro code get 
expanded into the resultant dial string. 

typedef struct DIALENV_MACRO_CODE 
{ 

CHAR symbols [ lenDialEnvMacroCode+1 ] ; 
} DIALENV_MACRO_CODE, *P_DIALENV_MACRO_CODE; 

typedef struct DIALENV_ENVIRONMENT 
{ 

DIALENV_DIAL_MODE dialMode; // Dial mode (tone /pulse) . 

DIALENV_OUTSIDE_LINE outsideLine; // Outside line/net access. 

DIALENV_AREA_CITY areaCity; // Area/City call originates from. 

DIALENV_COUNTRY country; // Country call originates from. 

DIALENV_INTL_ACCESS intlAccess; // International access code. 

DIALENV_LONG_DIST longDist; // Long distance access code. 

DIALENV_SUFFIX suffix; // Suffix applied to dial strings. 

DIALENV_MACRO_CODE macrocode [numDialEnvMacroCodes] ; // Macro/expand codes. 
} DIALENV_ENVIRONMENT, *P_DIALENV_ENVIRONMENT; 

Error Return Values: none, alw^ays returns stsOK. 
Symbols prefixed to a dialing string to gainaccess to the general switched telephone network. 



msgDialEnvBuildDialString 

Construct a dial string based upon the current dialing environment. 

Takes P_DIALENV_BUILD_DIALSTR, returns STATUS. Category: service action request. 

tdefine msgDialEnvBuildDialString MakeMsg(clsDialEnv, 5) 

typedef struct DIALENV_TELEPHONE_NUMBER 
{ 

CHAR country [lenDialEnvCountry+1] ; // Cntry call originates from. 

CHAR areaCity [lenDialEnvAreaCity+1] ; // Area/City call origs from. 

CHAR teleNumber[lenDialEnvTeleNumber+l] ; // Destination telephone #. 

CHAR postConnect [lenDialEnvPostConnect+1] ;//Post connect destination 

// network navigation code. 
} DIALENV_TELEPHONE_NUMBER, *P_DIALENV_TELEPHONE_NUMBER; 

The resultant string of symbols a dialer sends to either clsModem,the phone network, or another server 
which performs the dialing. 

typedef struct DIALENV_DIAL_STRING 
{ 

CHAR symbols [ lenDialEnvDialSt ring+1 ] ; 
} DIALENV DIAL STRING, *P DIALENV DIAL STRING; 
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typedef struct DIALENV_BUILD_DIALSTR 
{ 

P_DIALENV_TELEPHONE_NUMBER pTeleNumber; //In: Raw tele # to dial. 

P_DIALENV_DIAL_STRING pDialString; // Out: Resultant dial str. 
} DIALENV_BUILD_DIALSTR, *P_DIALENV_BUILD_DIALSTR; 

Comments NOTE: The order in which macro codes are processed is significant. All like macro codes are expanded 

before the next macro code is expanded. Thus if expansion of macro code N results in symbols for a 
subsequent macro code (e.g. N+1) to be inserted into the dial string, such symbols will be interpretted as 
and expanded as macro codes. 

Error Return Values: stsDialEnvDialStrTooLarge 



Class Messages 



msgNew | 

Creates an instance of a dialing environment. 

Takes P_DIALENV_NEW, returns STATUS. Category: class message. 

typedef DIALENV_ENVIRONMENT DIALENV_NEW_ONLY, *P_DIALENV_NEW_ONLY; 

tdefine dialenvNewFields \ 

serviceNewFields \ 

DIALENV_NEW_ONLY dialEnv; 

Argwments typedef struct DIALENV_NEW 

{ 

dialenvNewFields 
} DIALENV_NEW, *P_DIALENV_NEW; 

Comments Error Return Values: percolated up from other classes, none from clsDialEnv. 



msgNewDefaults 

Initializes the DIALENV_NEW structure to default values. 

Takes P_DIALENV_NEW, returns STATUS. Category: class message. 



Message typedef struct DIALENV_NEW 

Argiimeiifs { 

dialenvNewFields 
} DIALENV_NEW, *P_DIALENV_NEW; 

Commenfi Sets: 



pArgs->svc . style . waitForTarget = 

pArgs->svc.style.exclusiveOpen = 

pArgs->svc.style.autoOwnTarget = 

pArgs->svc . style . autoOpen 

pArgs->svc. style. autoMsgPass = 

pArgs->svc. style. checkOwner = false; 

pArgs->svc.pManagerList = pManagerList; // theLocations 

pArgs->svc.nuinManagers = 1; 

memset (& (pArgs->dialEnv) , 0, sizeof (pArgs->dialEnv) ) ; 

pArgs->dialEnv.dialMode = deTone; // Tone dialing. 

// All remaining struct dialEnv 
// fields are set to zero/null. 

Error Return Values: percolated up from other classes, none from clsDialEnv. 
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msgDialEnvGetMacroIds 

Passes back a string of symbols which identify dialing macro codes. 

Takes P_DIALENV_MACRO_IDS, returns STATUS. Category: class message. 

tdefine msgDialEnvGetMacroIds MakeMsg(clsDialEnv, 6) 

jmenfs typedef struct DIALENV_MACRO_IDS 

{ 

CHAR symbols [numDialEnvMacroCodes+1] ; 
} DIALENV_MACRO_IDS, *P_DIALENV_MACRO_IDS; 

itiients Error return values: percolated up from other classes, none from clsDialEnv. 

cIsDialEnv non-error status values 

None currently defined 

cIsDiolEnv error status values 

The request sent to the dialing environment has been denied because the request isn't supported by this 
dialing environment. 

#define stsDialEnvRequestDenied MakeStatus (clsDialEnv, 1) 

The request sent to the dialing environment specified an invalid country code. 

#define stsDialEnvInvalidCountry MakeStatus (clsDialEnv, 2) 

The request sent to the dialing environment contained data which didn't match the specified 
constraints. 

Idefine stsDialEnvNoMatch MakeStatus (clsDialEnv, 3) 

The dial string resulting from msgDialEnvBuildDialString is too large to be contained within struct 
DIALENV_DIAL_STRING. 

#define stsDialEnvDialStrTooLarge MakeStatus (clsDialEnv, 4) 

Message definitions •••. 

NOTE msg #1 reserved for private use. 

Action Messages 

msgDialEnvOptCardRefresh 

Refreshes a dialing environment option card (self) with the current dialing environment settings. 

Takes nothing, returns STATUS. Category: action request. 

#define msgDialEnvOptCardRefresh MakeMsg(clsDialEnvOptCard, 2) 

sinents A client should send msgDialEnvOptCardRefresh to a dialing environment option card when it 

receives msgOptionRefreshCard and the card tag matches that assigned to the dialing environment 
option card. 

Error Return Values: percolated up from other classes, none from clsDialEnv. 
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msgDialEnvOptCardApply 

Updates the dialing environment with current settings from a dialing environment option card (self). 

Takes nothing, returns STATUS. Category: action request. 

♦define msgDialEnvOptCardApply MakeMsg(clsDialEnvOptCard, 3) 

Comments A client should send msgDialEnvOptCardApply to a dialing environment option card when it receives 

msgOptionApplyCard and the card tag matches that assigned to the dialing environment option card. 

Error Return Values: percolated up from other classes, none from clsDialEnv. 

^ Class Messages t 

> 



msgNew 

Creates an instance of a dialing environment option card. u 

Takes P_DIALENV_OPTCARD_NEW, returns STATUS. Category: class message. 

Arguments typedef struct LOCATION_NAME 

{ 

CHAR name [nameBuf Length] ; // Name of a location. 

} LOCATION_NAME, *P_LOCATION_NAME; 

// Name of a dialing environment, 
typedef LOCATION_NAME DIALENV_NAME, *P_DIALENV_NAME; 

typedef struct DIALENV_OPTCARD_NEW_ONLY 
{ 

DIALENV_NAME dialEnv; // Name of DialEnv supplying info. 

U32 sparel; // unused (reserved) . 

U32 spare2; // unused (reserved) . 

} DIALENV_OPTCARD_NEW_ONLY, *P_DIALENV_OPTCARD_NEW_ONLY; 

tdefine dialenvOptCardNewFields \ 
customLayoutNewFields \ 

DIALENV_OPTCARD_NEW_ONLY dialenvOptCard; 

typedef struct DIALENV_OPTCARD_NEW 
{ 

dialenvOptCardNewFields 
} DIALENV_OPTCARD_NEW, *P_DIALENV_OPTCARD_NEW; 

Comments A client may add the dialing environment option card to its stack of of option cards, and create it in 

reponse to msgOptionProvideCard via this message. Clients may create multiple cards and insert them 
into any window. The cards needn't be part of an option card stack. 

NOTES: It is possible for one or more clients to create multiple dial environment option cards. Because 
of this, dialing environment option cards observe the dialing environment. When the dialing 
environment changes, ail dialing environment cards get refreshed with current dialing environment 
settings. 

The requestor must fill in the pArgs->dialEnv with the name 
of the location which will supply the option card with dialing 
environment settings. 

Error Return Values: percolated up from other classes, stsDialEnvOptCardBadEnvironment. 
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msgNewDefaults 

Initializes the DIALENV_OPTCARD_NEW structure to default values. 

Takes P_DIALENV_OPTCARD_NEW, returns STATUS. Category: class message. 

lessege typedef struct DIALENV_OPTCARD_NEW 

irguments { 

dialenvOptCardNewFields 
} DIALENV_OPTCARD_NEW, *P_DIALENV_OPTCARD_NEW; 

oriiments Sets: 

memset (pArgs->dialenvOpt Card. dialEnv. name, Nil (CHAR) , 
si zeof(pArgs->dialenvOpt Card. dialEnv. name) ) ; 

r cIsDialEnvOptCard non-error status values 

None currently defined 

|r cIsDialEnvOptCard error status values 

An internal system error was encountered creating an instance of cIsDialEnvOptCard. 

tdefine stsDialEnvOptCardProblem MakeStatus (cIsDialEnvOptCard, 1) 

The arguments specified via msgNew^ to cIsDialEnvOptCard didn't specify a dialing environment (from 
which data for the option card is obtained). 

tdefine stsDialEnvOptCardBadEnvironment MakeStatus (cIsDialEnvOptCard, 2) 

An internal system error was encountered unfiling cIsDialEnvOptCard from a resource file. 

tdefine stsDialEnvOptCardBadResFile MakeStatus (cIsDialEnvOptCard, 3) 

An internal system error was encountered when attempting to locate a window (containing option data) 
withing a dialing environment option card. 

tdefine stsDialEnvOptCardNoSuchOption MakeStatus (cIsDialEnvOptCard, 4) 



Message definitions 



msgNew 

Creates an instance of a dialing environment field. 

Takes P_DIALENV_FIELD_NEW, returns STATUS. Category: class message. 

tdefine dialenvFieldNewFields \ 
fieldNewFields 

Arguments typedef struct DIALENV_FIELD_NEW. 

{ 

dialenvFieldNewFields 
} DIALENV_FIELD_NEW, *P_DIALENV_FIELD_NEW; 

Comnierits clsDialEnvField logic within its msglnit method: 



DIALENV_MACRO_IDS macrolds; 

CHAR fieldCharList[20+numDialEnvMacroCodes+l] ; 

XTM_ARGS template; 

P STRING fieldChars = "01234567890 -,*t; ! "; 
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// 

// If the client hasn't modified the default field template value, 

// establish a template to coerce dialing environment field input. 

// 

// Query clsDialEnv to obtain the symbols identifying macro 

// codes. Append them to base dialing type characters. 

// 

if (pArgs->field.xlate.pTemplate == pNull && 

pArgs->field. style. xlateType == fstXlateTemplate) 
{ 

macrolds. symbols [0] =Nil(CHAR); 

ObjCallWarn(msgDialEnvGetMacroIds, clsDialEnv, &macroIds) ; 

strcpy (fieldCharList, fieldChars) ; 

strcat (fieldCharList, macrolds . symbols) ; 

template . xtmType = xtraTypeCharList; // Char list type template. 

template . xtmMode = xtmModeDefault; // No special template mode. 

template.pXtmData = fieldCharList; // The character list. 

pArgs->field.xlate.pTemplate = &template; Z 

} u 

// Call our ancestor to create the object, 
return ObjectCallAncestor (msg, self, pArgs, ctx) ; 

Error Return Values: percolated up from other classes, 

msgNewDefaults 

Initializes the DIALENV_FIELD_NEW structure to default values. 

Takes P_DIALENV_FIELD_NEW, returns STATUS. Category: class message. 

tessoge typedef struct DIALENV_FIELD_NEW 

Arguments { 

dialenvFieldNewFields 
} DIALENV FIELD NEW, *P DIALENV FIELD NEW; 



Comments Sets: 



// 

// Establish defaults for an instance of clsDialEnvField. 

// 

pArgs->field . style . veto 

pArgs->field. style. noSpace = 

pArgs->field. style. uppercase = true; 

pArgs->field. style. xlateType = fstXlateTemplate; 

pArgs->field.xlate.pTemplate = &template; 

pArgs->label . style . numCols 

pArgs->label. style. numRows = IsNumAbsolute; 

pArgs->label.cols = 12; 

pArgs->label.rows = 1; 

pArgs->border. style. edge = bsEdgeBottom; 

pArgs->border . style . topMargin 

pArgs->border . style .bottomMargin= bsMarginMedium; 

pArgs->border.style.borderInk = bsInkGray66; 
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FLAP.H 



This file contains the API definition for clsFLAP 

clsFLAP inherits from clsMILService 

This mil service provides the interface between the ALAP mil device and the rest of Penpoint. This 
interface allows for the configuring of the ALAP mil device and for PenTops networking using the 
ALAP mil device. The flap mil service will typically only be accessed by link level drivers since the mil 
service is responsible for providing the lowest levels of the PenTops protocol stack. 

This mil service responds to the messages defined in the link.h header file. Refer to link.h for message 
definitions. 

You access this mil service by using the standard service access techniques. These techniques are 
discribed in servmgr.h. 

The flap mil service is a member of the 'theLinkHandlers' service manager. 

tifndef FLAP_INCLUDED 
♦define FLAP_INCLUDED 

tifndef MIL_SERVICE_INCLUDED 

♦include <milserv.h> 

tendif 

#ifndef LINK_INCLUDED 

tinclude <link.h> 

tendif 



msgNew 

creates a new flap object. 

Takes P_FLAP_NEW, returns STATUS. 

tdefine flapNewFields \ 
milServiceNewFields \ 

typedef struct FLAP_NEW { 

flapNewFields 
} FLAP_NEW, *P_FLAP_NEW; 

STATUS EXPORTED ClsFLAPInit (void) ; 



;fiiii;iiii;il*i^^^ 
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HSLINK.H 



This file contains the definition and methods for clsALAPHighSpeed. 
clsALAPHighSpeed inherits fi:om clsLink (see Hnk.h). 

tifndef HSLINK_INCLUDED 

#define HSLINK_INCLUDED 

tdefine alapHighSpeedNewFields serviceNewFields 

typedef struct ALAP_HSLINK_NEW 

{ 

alapHighSpeedNewFields 
} ALAP_HSLINK_NEW, *P_ALAP_HSLINK_NEW; 
STATUS EXPORTED ClsALAPHSLinklnit (void) ; 






^. 



%fi. 




HSPKT.H 



This file contains the API definition for clsHighSpeedPacket. 
clsHighSpeedPacket inherits from clsService. 
Provides a high speed packet transfer API. 

tifndef HSPKT_INCLUDED 
♦define HSPKT_INCLUDED 

tifndef GO_INCLUDED 
tinclude <go.h> 
#endif 

tifndef MILSERV_INCLUDED 
tinclude <milserv.h> 
tendif 

tifndef CLSMGR_INCLUDED 
tinclude <clsmgr.h> 
tendif 

tifndef DVHSPKT_INCLUDED 
tinclude <dvhspkt.h> 
tendif 



U16 


version; 


U16 


status; 


U32 


asyncBaud; 


U16 


parConnectChar ; 



Common #clefiiies and typedefs 

typedef struct HS_PACKET_METRICS 

{ 

// version number 
// current status 

// baud rate for asynch serial mode 
// connect character for connection 
// testing (parallel mode only!) 
// character to return upon reception 
//of parConnectChar (parallel mode 
// only!) 

// default lead in character 
// default acknowledgement character 
// (return upon reception of 1st data 
// byte or of packet lead in character 
// if one is defined) . 
MIL_HS_PACKET_DEVICE_TYPE deviceType; // device type (see dvhspkt.h) 

} HS_PACKET_METRICS, *P_HS_PACKET_METRICS; 

typedef OBJECT HS_PACKET, *P_HS_PACKET; 

tdefine stsHSPacketBusy MakeStatus (clsHighSpeedPacket, 1) 



U16 



U16 
U16 



parConnectAckChar ; 



leadlnChar; 
dataAckChar; 



High Speed Packet Class Messages 



msgHSPacketStatus 

Returns the current status of the high speed packet device. 
Takes P_HS_PACKET_STATUS, returns STATUS. 



tdefine msgHSPacketStatus 
tdefine hsPktStsBusy 



MakeMsg (ClsHighSpeedPacket, 3) 
flagO // status 
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Arsiitiienfs typedef struct HS_PACKET_STATUS 

{ 

U16 status; 
} HS PACKET STATUS, *P HS PACKET STATUS; 



msgHSPacketSendPacket 

Sends one packet through high speed packet device. 

Takes P_HS_PACKET_SEND_PACKET, returns STATUS. 

#define msgHSPacketSendPacket MakeMsg(clsHighSpeedPacket, 9) 

Argonrsenfs typedef struct HS_PACKET_SEND_PACKET 

{ 

P_UNKNOWN pBuf; 

U32 numBytes; 

U16 firstByte; 

} HS_PACKET_SEND_PACKET, *P_HS_PACKET_SEND_PACKET; 

C0mments If leadlnChar (in metrics) is zero, firstByte is used as lead in character. If both are zero, no lead in 

character is sent. 



msgHSPacketSetCharHandler 

Installs character receive handler. 

Takes P_HS_PACKET_CHAR_HANDLER, returns STATUS. 

#define msgHSPacketSetCharHandler MakeMsg(clsHighSpeedPacket,10) 

Arguments 

¥unttmn Prototype U32 userData) ; 

typedef struct HS_PACKET_CHAR_HANDLER 
{ 

P_HS_PACKET_RX_HANDLER pRxHandler; 

U32 userData; 

} HS_PACKET_CHAR_HANDLER, *P_HS_PACKET_CHAR_HANDLER; 

Comments HSPacket calls the user-defined function when a character is received. The called fiicntion must collect 

the provided character and return either true if the packet is complete, false otherwise. 

userData in HS_PACKET_RX_HANDLER is the user-provided userData U32 in 
HS_PACKET_CHAR_HANDLER. 

If leadlnChar (in metrics) is zero, the first character received is contained in both the firstByte and the 
receivedByte parameters to P_HS_PACKET_RX_HANDLER(). 

The received character handler will not be installed if one already is. See 
msgHSPacketFreeCharHandler. 

The character handler is automatically freed when the service is closed. 

msgHSPacketFreeCkarHandler 

Deinstalls a previously installed character receive handler. 

Takes P_HS_PACKET_CHAR_HANDLER, returns STATUS. 

♦define msgHSPacketFreeCharHandler MakeMsg(clsHighSpeedPacket,ll) 

Message typedef struct HS_PACKET_CHAR_HANDLER 

Arguments { 

P_HS_PACKET_RX_HANDLER pRxHandler; 
U32 userData; 

} HS PACKET CHAR HANDLER, *P HS PACKET CHAR HANDLER; 
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Function prototypes 

msgHSPacketEnable 

Starts the continuous function which tests for connection and make ourselves "visible" to others. 

Takes nothing, returns STATUS. 

tdefine msgHSPacketEnable MakeMsg(clsHighSpeeciPacket, 12) 

msgHSPacketDisable 

Stops the continuous function (started by msgHSPacketEnable) which tests for connection and become 
"invisible". 

Takes nothing, returns STATUS. 

tdefine msgHSPacketDisable MakeMsg(clsHighSpeedPacket, 13) 



u 



Z 

msgNew o 

Creates a new hspkt object. 

Takes P_HS_PACKET_NEW, returns STATUS. 

tdefine hspktNewFields \ 
milServiceNewFields 

jments typedef struct HS_PACKET_NEW { 
hspktNewFields 
} HS_PACKET_NEW, *P_HS_PACKET_NEW; 

Function prototypes 

tioti Prototype STATUS EXPORTED ClsHSPacketlnit (void) ; 
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INBXSVC.H 



This file contains the API definition for clsINBXService. 
clsINBXService inherits from clsIOBXService. 

Provides default behavior for Inbox Services. 

tifndef INBXSVC_INCLUDED 
♦define INBXSVC_INCLUDED 

tifndef IOBXSVC_INCLUDED 
#include <iobxsvc.h> 
fendif 



Introduction 



In PenPoint, input operations are handled by a special class of services known as the "inbox services." 
While most input operations are triggered by an external event such as an incoming fax image from a 
remote fax machine, some input operations may require that the PenPoint computer be one that 
initiates the communication process. For example, a fax input service may wish to periodically "poll" a 
"store-and- forward" facility in order to receive a fax image. Thus, an inbox service implements the 
"deferred input" feature in PenPoint: This concept permits a user to specify input operations regardless 
of the readiness of input devices. If the input device (e.g., a data/fax modem, a LAN connection, etc.) is 
not available or not connected, the input process is deferred until the input device becomes ready. 



Passive vs. Active Inbox Services 

The simplest type of inbox services are those who passively wait for an input event to happen. That is, 
after the input operation is initiated by a remote agent such as a fax machine, the inbox service running 
on a PenPoint computer detects the input event and then receives the incoming data stream. This type 
of inbox services do not initiate an input operation by themselves. Typically, when such a service is 
enabled by the user, it simply becomes the owner of the I/O device. A simple fax inbox service, for 
example, becomes the owner of the fax modem and sets it up to start receiving fax images whenever a 
phone call comes in. While the inbox service owns the I/O device, no other services can transmit or 
receive data through the same device. (For more details on the notion of service ownership, see the 
service API in service.h.) 

Some inbox services may want to actively "solicitate" input from a remote agent. For example, a service 
that queries a remote database will have to establish the communication link between the PenPoint 
computer and the remote database server. For this type of services, clsINBXService provides default 
behaviors to manage the state of the I/O device (connected or disconnected), the permission to initiate 
input operation (whether the service is enabled or disabled), as well as automatic polling behavior 
similar to that of an outbox service. Thus, the user can "defer" the input operation until it becomes 
possible to establish a communication link with a remote agent. See the API for cIsOBXService for a 
detailed discussion of the deferred input/output protocol. Note, however, that to enable such 
outbox-like behavior, the polling flag must be turned on when the service is created. I.e., in 
msgNewDefaults, you should set 



pArgs->iobxsvc . in . autoPoll 



= true; 
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Inbox Documents 

Normal!^, documents can be automatically created in an inbox section as the end result of an input 
event. For example, a fax inbox section may create a document containing the fax images receieved in 
the fax modem. Such documents are normal PenPoint documents. Their contents have nothing to do 
with the input device or where the document came from. 

Sometimes an inbox document contains not only data, but also some control information about the 
input operation to be performed. For example, taking advantage of the "deferred input" feature, the user 
may construct a specific query statement for an online database and put it into the appropriate inbox 
section before the PenPoint machine is physically connected to the remote database. When the input 
service becomes ready, the query statement is sent to the remote database, and the result is put into 
either another document or the same document containing the query statements. This type of inbox 
documents is very similar to the outbox document that controls the actual output operation. Again, for 
more information about the deferred input/output protocol, see obxsvc.h. 

Note that the deferred I/O protocol implemented by clsINBXService assumes that an input operation is 
controlled by an inbox document: an assumption that may be too cumbersome and confusing for many 
services. If such is the case, an inbox service can simply store the input control information (e.g., a 
database query statement) with the service itself When the service receives 

msglNBXSvcPollDocuments, it simply handles the input operation directly and bypasses the rest of the 
protocol. 

Services that Handle Input and/or Output 

clsINBXService deals only with input operations. For those services that want to handle output 
operations or both input and output at the same time, two other classes, clsOBXService and 
clsIOBXService, are provided by PenPoint. In fact, clsINBXService and clsOBXService are 
implemented as a subclass (hence a subset) of clsIOBXService. 



Class Messages 



msgNewDefaults 

Initializes the P_INBXSVC_NEW structure to default values. 
Takes P_INBXSVC_NEW, returns STATUS. Category: class message. 

typedef struct INBXSVC_NEW_ONLY { 

OBJECT sectionClass; // class of the inbox section 

// This must be clsNBToc or a subclass of it. 

U32 unusedl; 

U32 unused2 ; 

U32 unusedS; 
} INBXSVC_NEW_ONLY, *P_INBXSVC_NEW_ONLY; 

#define inbxServiceNewFields \ 
ioSvcNewFields \ 

INBXSVC_NEW_ONLY inbxsvc; 

typedef struct INBXSVC_NEW { 

inbxServiceNewFields 
} INBXSVC_NEW, *P_INBXSVC_NEW; 

Zeroes out pArgs->inbxsvc and sets...>iobxsvc.in.autoPoll = false;>inbxsvc.sectionClass 

clsNBToc; 
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Argymenfs 



Comments 



msgNew 

Creates a new inbox service object. 

Takes P_INBXSVC_NEW, returns STATUS. Category: class message. 

typedef struct INBXSVC_NEW { 

inbxServiceNewFields 
} INBXSVC_NEW, *P_INBXSVC_NEW; 

msglNBXSvcSwitchlcon 

Toggles the inbox icon (to empty or filled) if neccessary. 

Takes nothing, returns STATUS. Category: class message. 

Idefine msglNBXSvcSwitchlcon msglOBXSvcSwitchlcon 

Check the content of the inbox notebook. Show the "filled" icon if any document is found. Show the 
"emtpy" icon otherwise. 



Argiimer 



msglNBXDocGetService 

Gets the service name. 

Takes P_INBX_DOC_GET_SERVICE, returns STATUS. Category: class message. 

tdefine msglNBXDocGetService msglOBXDocGetService 

typedef struct INBX_DOC_GET_SERVICE { 

OBJECT document; // In: document uid 

CHAR svcName [nameBuf Length] ; // Out: service name 

} INBX_DOC_GET_SERVICE, *P_INBX_DOC_GET_SERVICE; 

Get the name of the service associated with an inbox document. If the document has not been placed 
into an inbox section, stsFailed is returned. 

Note that the document must be at the top level of an inbox section. That is, if the document is 
embedded within another document, which is in an inbox section, stsFailed will be returned. 



msglNBXDocInlnbox 

Checks if a document is in a section in the Inbox. 

Takes P_INBX_DOC_IN_INBOX, returns STATUS. Category: class message. 

tdefine msglNBXDocInlnbox msglOBXDocInlOBox 

typedef struct INBX_DOC_IN_INBOX { 

UUID uuid; // In: document uuid 

CLASS svcClass; // In: service class to check for 

} INBX_DOC_IN_INBOX, *P_INBX_DOC_IN_INBOX; 

This message can be sent to clsINBXService to check if a PenPoint document represented by 
pArgs->uuid is already in the input queue of an inbox service inheriting from pArgs->svcClass. stsOK is 
returned if it is, stsFailed otherwise. If pArgs->svcClass is objNull, stsOK is returned if the document is 
anywhere in the Inbox notebook. 
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Messages Sent to an Inbox Service Instance 



msglNBXSvcMovelnDoc 

Moves a document into the inbox section. 

* 

Takes P_INBXSVC_MOVE_COPY_DOC, returns STATUS. 

#define msglNBXSvcMovelnDoc msglOBXSvcMovelnDoc 

typedef struct INBXSVC_MOVE_COPY_DOC { 

FS_LOCATOR source; // In: Location of source document. 

U16 sequence; // In: Sequence number to move/copy 

// in front of. 

} INBXSVC_MOVE_COPY_DOC, *P_INBXSVC_MOVE_COPy_DOC; 

rotiiments Superclass behavior is to move the document located at pArgs->source into the input queue associated 

with the inbox service. For example, set pArgs->sequence to 1 to move the document to the top of the 
queue. Set it to maxU16 to move the document to the bottom of the queue. 

After the document is moved (or copied) to the input queue, it is considered to be in a state ready for 
input, even though the service may not be connected at the time. Client should not alter the document 
in any way once it has been moved to the input queue. 

Subclasses can provide their own behavior if they wish. Remember to use the class message 
msglNBXSvcSwitchlcon to change the inbox icon. 

msglNBXSvcCopylnDoc 

Copies a document into the Inbox section. 

Takes P_INBXSVC_MOVE_COPY_DOC, returns STATUS. 

fdefine msglNBXSvcCopylnDoc msglOBXSvcCopylnDoc 

iSessoge typedef struct INBXSVC_MOVE_COPY_DOC { 

Irgumenfs FS_LOCATOR source; // In: Location of source document. 

U16 sequence; // In: Sequence number to move/copy 

// in front of. 

} INBXSVC_MOVE_COPY_DOC, *P_INBXSVC_MOVE_CGPY_DOC; 

:omrneiits Same as msglNBXSvcMovelnDoc, except that the document is copied to the input queue. 

msglNBXSvcGefiTempDir 

Passes back a handle for a temporary directory. 

Takes P_OBJECT, returns STATUS. 

♦define msglNBXSvcGetTempDir msglOBXSvcGetTempDir 

Zommimts This message is provided for clients who may want ot prepare their input document before moving it 

into the input queue. The handle of an "official" temporary directory is passed back and it can be used 
as temporary storage for documents, data, etc. Clients are responsible for deleting temporary files when 
they are done. The directory will be flushed after a warm boot. 

msglNBXSvcPollDocuments 

Polls all documents in an input queue and input those who are ready. 

Takes nothing, returns STATUS. 

tdefine msglNBXSvcPollDocuments msglOBXSvcPollDocuments 
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Comments This message tells the inbox service to look through its input queue and send out the first document 

ready for input. The service will first make sure that it is enabled and is connected to the designated 
input port. If these conditions are met, it will then self-send msglNBXSycNextDocument to locate the 
next document ready for input. 

If msglNBXSvcNextDocument returns stsOK, indicating that a document is ready for input, this 
message proceeds to self-send msglNBXSvcLockDocument to lock the document, and finally 
msglNBXSvcInputStart to initiate the input process. 

If msglNBXSvcNextDocument returns stsINBXSvcDocReady, indicating that the section is not empty 
but none of the documents are ready for input, this message self-sends 
msglNBXSvcScheduleDocument to schedule the document passed back in pArgs at a later time. 

Subclasses normally do not process this message. 

See Also msglNBXSvcNextDocument 

msglNBXSvcNextDocument 

Passes back the next document ready for input. 

Takes P_INBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msglNBXSvcNextDocument msglOBXSvcNextDocument 

Arguments typedef Struct INBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} INBXSVC_DOCUMENT, *P_INBXSVC_DOCUMENT ; 

Comments Superclass behavior is to start from the top of the input queue and locate the first document ready for 

input. If one is found, information about the document is passed back in pArgs. The same pArgs will be 
passed to messages msglNBXSvcLockDocument and msglNBXSvcInputStart. By default, a document 
is ready for input when it is closed. If the document is open, it will receive msglNBXDocInputStartOK 
and it should return stsOK to indicate that it is ready for input. 

Subclasses can provide their own behavior if they wish. Return stsINBXSvcSectionEmpty to give the 
superclass an opportunity to change the inbox icon from filled to empty. 

ietiirm ¥ciltie stsOK A document is ready for input. 

StsINBXSvcSectionEmpty The input queue is empty. 

stsINBXSvcDocNotReady No document in the input queue is ready. 

Service-Specific Error Returns. 
See Also msglNBXSvcPoUDocuments 

msglNBXSvcLockDocumient 

Locks the document in preparation for input. 

Takes P_INBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msglNBXSvcLockDocument msglOBXSvcLockDocument 



OBJECT 


uid; 


OBJECT 


dir; 


OBJECT 


docClass; 


U16 


sequence; 


CHAR 


pName [nameBuf Length] ; 


P UNKNOWN 


pDocData; 
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soge typedef struct INBXSVC_DOCUMENT { 

// uid of the doc 
// app dir of the doc 
// class of the doc 
// sequence of the doc 
// name of this doc 
// subclass' s private data 
} INBXSVC_DOCUMENT, *P_INBXSVC_DOCUMENT; 

This message is a place holder for subclasses that may require additional preparatory work to be 
performed on a document before it is ready for input. For example, a document may have to be 
"locked" so that it can not be opened during the input process. This message may be used for other 
purposes as well. For example, an inbox service may decide to store a light-weight "shadow" document 
(e.g., a report designator for a database application) in the input queue until it is chosen for input. The 
service then handles this message by converting the shadow document to a real one (e.g., the actual 
report). 

The superclass behavior for this message is to stamp the document directory with the filesystem attribute 
iobxsvcDocInputlnProgress. This stamp will prevent any gestures over the document from being 
processed. This means that once a document is locked for input it can not be deleted, renamed, etc. via 
gestures. 

msglNBXSvcUnlockDocument 

msglNBXSvcUnlockDocument 

Unlocks a document that was previously locked. 

Takes P_INBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

Idefine msglNBXSvcUnlockDocument msglOBXSvcUnlockDocument 

ige typedef struct INBXSVC_DOCUMENT { 

ArfiiiTierits OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} INBXSVC_DOCUMENT, *P_INBXSVC_DOCUMENT ; 

Cortirnsnts This message is a place holder for subclasses that may require additional "cleanup" work to be 

performed on a document before it is put back to the input queue. 

The superclass behavior for this message is to remove the iobxsvcDocInputlnProgress stamp on the 
document directory. 

. . msglNBXSvcLockDocument 

msglNBXSvcScheduleDocument 

Schedules a document that is not ready for input 

Takes P_INBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

#define msglNBXSvcScheduleDocument msglOBXSvcScheduleDocument 

Message typedef struct INBXSVC_DOCUMENT { 

y-goments OBJECT uid; // uid of the doc 

// app dir of the doc 
// class of the doc 
// sequence of the doc 
// name of this doc 
// subclass' s private data 
} INBXSVC DOCUMENT, *P INBXSVC DOCUMENT; 



OBJECT 


uid; 


OBJECT 


dir; 


OBJECT 


docClass; 


U16 


sequence; 


CHAR 


pName [nameBuf Length] ; 


P_UNKNOWN 


pDocData; 
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Zomments This message is sent when msglNBXSvcNextDocument locates a document in the input queue but the 

document is not ready for input. 

Subclasses should provide their own behavior. The default behavior is to release the ownership of the 
target service (i.e., become disabled), with the expectation that the user must manually schedule the 
document later on (by re-enabling the section.) 

iee Also msglNBXSvcNextDocument 

msglNBXSvcInputStart 

Starts the input process for a document in the input queue. 

Takes P_INBXSVC_DOCUMENT, returns STATUS. Category: self-sent. t 

> 
tdefine msglNBXSvcInputStart msglOBXSvcIOStart 5 

■II 

lessage typedef Struct INBXSVC DOCUMENT { Z 

O 



OBJECT 


uid; 


// uid of the doc 


OBJECT 


dir; 


// app dir of the doc 


OBJECT 


docClass; 


// class of the doc 


U16 


sequence; 


// sequence of the doc 


CHAR 


pName [nameBuf Length] ; 


// name of this doc 


P_UNKNOWN 


pDocData; 


// subclass' s private data 



} INBXSVC_DOCUMENT, *P_INBXSVC_DOCUMENT; 

Superclass behavior is to activate the inbox document if it isn't already active, and then send 
msglNBXDocInputStart to the document instance. 

Subclasses can provide their own behavior if they wish. 



msglNBXSvcInputCancel 

Cancels the input process. 

Takes nothing, returns STATUS. 

#define msglNBXSvcInputCancel msglOBXSvcIOCancel 

This message is sent to the service when the caller wishes to cancel any input operation in progress. The 
service responds to this message by sending msglNBXDocInputCancel to an active inbox document. 
After the document is cancelled, the service will post an error note to the user if there are other 
documents waiting to be processed. The user then decides whether or not the service should proceed to 
send the remaining documents. 

Subclasses do not normally process this message. 



msglNBXSvcInputCleanUp 

Cleans up after the current input is done. 

Takes P_INBX_DOC_INPUT_DONE, returns STATUS. Category: self-post.. 

tdefine msglNBXSvcInputCleanUp msglOBXSvcIOCleanUp 

Enum32{INBX_DOC_EXIT_BEHAVIOR) { 

inbxDocExitDoNothing, 

inbxDocExitDelete , 

inbxDocExitMarkAsFailed, 

inbxDocExitMarkAsCancelled 
}; 
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typedef struct INBX_DOC_INPUT_DONE { 

INBX_DOC_EXIT_BEHAVIOR behavior; // exit behavior 

P_UNKNOWN pDocData; // Unused: document specific data 

} INBX_DOC_INPUT_DONE, *P_INBX_DOC_INPUT_DONE ; 

This message is posted to self as a result of the service receiving msglNBXDocInputDone, which is sent 
by the inbox document when it finishes the input operation. The inbox document will be either deleted 
or marked as specified in pArgs, and when everything is properly cleaned up the service will post 
msglNBXSvcPoliDocuments to self to see if anything else is waiting for input. 

Subclasses do not normally process this message. 

msglNBXDocInputDone 



msglNBXSvcStateChanged 

Tells observers that the service state just changed. 

Takes OBJECT, returns STATUS. Category: observer notification.. 

tdefine msglNBXSvcStateChanged msglOBXSvcStateChanged 

Informs observers that the state of a service has just changed. pArgs is the UID of the service. 

msglNBXSvcQueryState 

Passes back the state of the service. 

Takes P_INBXSVC_QUERY_STATE, returns STATUS. 

#define msglNBXSvcQueryState msglOBXSvcQueryState 

typedef struct ( 

BOOLEAN enabled; // true if the service is enabled. 

CHAR status [nameBufLength] ; // text describing the status of 

// the service. 

CHAR docName [nameBufLength] ; // document being processed 

P_UNKNOWN pStateData; // subclass' s private data 

} INBXSVC_QUERY_STATE, *P_INBXSVC_QUERY_STATE; 

This message is typically used to query what state the service instance is in. 

msglNBXSvcGetEnabTed 

Gets the enabled state of the service. 

Takes P_BOOLEAN, returns STATUS. 

tdefine msglNBXSvcGetEnabled msglOBXSvcGetEnabled 

Subclasses can override this message and redefine the notion of "enabled." The default behavior of the 
superclass is to equate "enabled" with the ownership of the target service (i.e., input device). That is, the 
service is "enabled" when it owns the target service. By appending to or replacing the default behavior, a 
subclass can define additional conditions which must be met before a service is considered enabled. 

msglNBXSvcSetEnabled 

Sets the enabled state of the service. 

Takes BOOLEAN, returns STATUS. 

♦define msglNBXSvcSetEnabled msglOBXSvcSetEnabled 



snfs 
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Comments This message is sent to the service in response to service notification messages msgSvcOwnerAcquired 

and msgSvcOwnerReleased. Subclasses can provide their own behavior and thereby redefine the notion 
of "enabled" for the service. If they do, they must pass this message up to the ancestor so that observers 
of the inbox service will be properly notified. 

P Inbox Document Messages 

Asks the inbox document if it is OK to start the input process 

Takes nothing, returns STATUS. >. 

tdefine msglNBXDocInputStartOK msglOBXDocIOStartOK p 

When an inbox service finds an opened document in the inbox section, it sends this message to the z 

document instance, asking whether it's OK to start the input operation while the document remains 
open. When the document receives this message, it should return stsOK to give the service permission 
to begin the input process. An error status, including stsNotUnderstood, is taken to mean that the 
document instance vetos the request and the service will not start the input process. 

msglNBXDocInputStart 

Tells an inbox document to start the input process. 

Takes nothing, returns STATUS. 

#define msglNBXDocInputStart msglOBXDocIOStart 

This message is sent by the inbox service to a document. The document should respond to this message 
by starting the input process. 

msglNBXDocInputDone 

Tells the inbox service that input is finished. 

Takes P_INBX_DOC_INPUT_DONE, returns STATUS. Category: client responsibility. 

tdefine msglNBXDocInputDone msglOBXDocIODone 

typedef struct INBX_DOC_INPUT_DONE { 

INBX_DOC_EXIT_BEHAVIOR behavior; // exit behavior 

P_UNKNOWN pDocData; // Unused: document specific data 

} INBX_DOC_INPUT_DONE, *P_INBX_DOC_INPUT_DONE; 

When the input process is finished, the inbox document in charge of the input should send this message 
to the inbox service. This message must be sent even if the input process has been aborted. The pArgs 
for this message tells the inbox service what to do with the inbox document. If inbxDocExitDelete is 
specified, the document will be removed from the inbox. In all other cases the document will be 
unlocked and left in the inbox. If either inbxDocExitMarkAsCancelled or inbxDocExitMarkAsFailed 
are specified, the name of the document will be altered to provide visual indication for the user that the 
input process has not completed successfiilly. 

msglNBXDocGetService 
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msglNBXDocInputCancel 

Tells an inbox document to cancel the input process. 

Takes nothing, returns STATUS. 

fdefine msglNBXDocInputCancel msglOBXDocIOCancel 

Cotiiments This message is used by the inbox service to inform a document that it should cancel the input process. 

The document should handle this message by terminating its input operation and then sending 
msglNBXDocInputDone to the service with pArgs->behavior set to inbxDocExistMarkAsCancelled. 

msglNBXDocStatusChanged 

Tells the inbox service that the document status is changed. 

Takes P_INBX_DOC_STATUS_CHANGED, returns STATUS. Category: client responsibility. 

#define msglNBXDocStatusChanged msglOBXDocStatusChanged 

typedef struct INBX_DOC_STATUS_CHANGED { 

CHAR status [nameBuf Length] ; // Text describing document state 

P_UNKNOWN pDocData; // Unused: document -specific data 

} INBX_DOC_STATUS_CHANGED, *P_INBX_DOC_STATUS_CHANGED; 

This message is sent by the inbox document to the service whenever its status has just changed. This 
status is displayed on Status column for the inbox section, in the Inbox notebook. 
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lOBXSVCH 



This file contains the API definition for clsIOBXService. 
clsIOBXService inherits fi-om clsService. 

tifndef IOBXSVC_INCLUDED 
tdefine IOBXSVC_INCLUDED 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

tendif 

tifndef GO_INCLUDED 

#include <go.h> 

tendif 

tifndef SERVICE_INCLUDED 

tinclude <service.h> 

tendif 

tifndef AUXNBMGR_INCLUDED 

tinclude <auxnbmgr . h> 

tendif 



Introduction 



clsIOBXService implements most of the behavior of its two subclasses: clsOBXService (Outbox service 
class) and clsINBXService (Inbox service class). While its subclasses deal with either the system Inbox or 
the system Outbox, clsIOBXService allows a service to access both the Inbox and the Outbox at the 
same time. For details about the two subclasses of clsIOBXService, see inbxsvc.h and obxsvc.h. 



Choosing the Appropriate Superclass for Your Service 

An Outbox service is assigned a section in the system Outbox. Thus, if a service's primary fiinction is to 
send data out of a PenPoint computer, it should probably be a subclass of clsOBXService. A good 
example for this type of services is a printer device driver. Avery important behavior for an Outbox 
service is to hold the output data until the physical device is available. This "deferred output" feature 
allows any documents in an Outbox section to be sent only when the conditions are right for the output 
operation to commence. This is implemented as a series of messages associated with 
msglOBXSvcPollDocumens, which basically "polls" the Outbox section looking for documents to be 
sent out. By default, all Outbox services inherit such auto polling behavior. (See the IOBXSVC_NEW 
structure defined in this API for inhibiting this behavior.) 

Similary, an Inbox service is associated with a section in the system Inbox and concerns itself with 
transfering data into a PenPoint computer. For example, the device driver for an optical scanner should 
probably be a subclass of clsINBXService. However, the notion of "deferred input" may not apply to 
most types of Inbox services. Therefore an Inbox service by default does not "poll" the documents in its 
Inbox section. When "deferred input" does make sense, as in the case of a stock quote service 
periodically downloading the latest stock prices from a host computer, the auto polling behavior can be 
easily enabled through the newArgs. 

Some services may need to transfer data both into and out of the PenPoint computer. (E.g., an electronic 
mail service.) There are several alternatives to deal with this situation. First, such services can still 
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subclass from either clsINBXService or clsOBXService and avoid the complexity of dealing with two 
separte sections in the system Inbox and Outbox. Second, the input and output operations can be 
divided into two services, one inheriting from clsINBXService and one inheriting from clsOBXService. 
Third, the service can inherit directly from clsIOBXService and deal with both an Inbox section and an 
Outbox section at the same time. Both sections will have the same name as the service itself, and 
enabling one of them will automatically enable the other. 



Common #clefines and typedefs 



Inbox/Outbox Service Status Codes 

The inbox/outbox section associated with the service is empty. This status is returned by 
msglOBXSvcNextDocument. 

#define stsIOBXSvcSectionEmpty MakeStatus (clsIOBXService, 101) 

The outbox section associated with the service is not empty, but none of the document is ready for 
output. This status is returned by msglOBXSvcNextDocument. 

tdefine stsIOBXSvcDocNotReady MakeStatus (clsIOBXService, 102) 



Outbox Service Standard Dialog Codes 



#define tagOBXSvcDocumentExists 
#define tagOBXSvcOutputPending 



MakeDialogTag (clsOBXService, 0) 
MakeDialogTag (clsOBXService, 1) 



Inbox Service Standard Dialog Codes 

#define taglNBXSvcDocumentExists 
#define taglNBXSvclnputPending 



MakeDialogTag (clsINBXService, 0) 
MakeDialogTag (clsINBXService, 1) 



Filesystem Attributes 

The state of a document in the inbox/outbox. 



#define iobxsvcAttrDocState 
Enum32 ( IOBXSVC_ATTR_DOC_STATE ) { 
iobxsvcDocNotScheduled 



iobxsvcDocOutputlnProgress 


= 


1, 


iobxsvcDocUserCancelled 


= 


2, 


iobxsvcDocError 


= 


3, 


iobxsvcDocInputlnProgress 


= 


4, 


iobxsvcDocReservedS 


= 


5, 


iobxsvcDocReserved6 


= 


6, 


iobxsvcDocReservedV 


= 


7, 


iobxsvcDocReservedS 


= 


8, 


iobxsvcDocReserved9 


= 


9, 


iobxsvcDocReservedlO 


= 


10, 


iobxsvcDocReservedl 1 


= 


11, 


iobxsvcDocReservedl2 


= 


12, 


iobxsvcDocReservedl 3 


= 


13, 


iobxsvcDocReservedl 4 


= 


14, 


iobxsvcDocReservedlS 


= 


15 



FSMakeFix32Attr (clsIOBXService, 1) 

= 0, // Document hasn't been scheduled 
// Same as no attribute. 
// Output started, not finished yet 
// Cancelled by user 
// Unable to finish due to errors 
// Input started, not finished yet 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
// Reserved for future expansion 
= 15 // Reserved for future expansion 
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Class Messages 



msgNewDefaults 

Initializes the P_IOBXSVC_NEW structure to default values. 

Takes P_IOBXSVC_NEW, returns STATUS. Category: class message. 

typedef struct IOBXSVC_SECTION_METRICS { 

BOOLEAN autoPoll; // True if svc should poll documents when 

// it's both enabled and connected. 
CLASS sectionClass; // Section Class. Must be clsNBToc or 

//a subclass of it, or objNull for none. 
U32 reserved[2] ; // Reserved. 
} IOBXSVC_SECTION_METRICS, *P_IOBXSVC_SECTION_METRICS; 

typedef struct IOBXSVC_NEW_ONLY { 

IOBXSVC_SECTION_METRICS in; // Inbox section spec | 

IOBXSVC_SECTION_METRICS out; // Outbox section spec O 

U32 reserved [3]; " 

} IOBXSVC_NEW_ONLY, *P_IOBXSVC_NEW_ONLY; 

tdefine ioSvcNewFields \ 
serviceNewFields \ 
IOBXSVC_NEW_ONLY iobxsvc; 

typedef struct IOBXSVC_NEW { 

ioSvcNewFields 
} IOBXSVC_NEW, *P_IOBXSVC_NEW; 

Zeroes out pArgs->iobxsvc. 

msgNew 

Creates a new inbox/outbox service object. 

Takes P_IOBXSVC_NEW, returns STATUS. Category: class message. 

tessege typedef struct IOBXSVC_NEW { 

w-Quments ioSvcNewFields 

} IOBXSVC_NEW, *P_IOBXSVC_NEW; 

msglOBXSvcSwitchlcon 

Toggles the inbox or outbox icon (to empty or filled) if neccessary. 

Takes nothing, returns STATUS. Category: class message. 

#define msglOBXSvcSwitchlcon MakeMsg(clsIOBXService, 1) 

ommenfs Check the content of the inbox or outbox notebook. For outbox, show the "filled" icon if any document 

is found. For inbox, show the "filled" icon if there is at least one document that has not been opened. 

msglOBXDocGetService 

Gets the service name. 

Takes P_IOBX_DOC_GET_SERVICE, returns STATUS. Category: class message. 

#define msglOBXDocGetService MakeMsg(clsIOBXService, 2) 

typedef struct IOBX_DOC_GET_SERVICE { 

OBJECT document; // In: document uid 

CHAR svcName[nameBufLength] ; // Out: service name 

} lOBX DOC GET SERVICE, *P lOBX DOC GET SERVICE; 
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Get the name of the service associated with an inbox/outbox document. If the document has not been 
placed into an inbox/outbox section, stsFailed is returned. 

Note that the document must be at the top level within an inbox/outbox section. That is, if the 
document is embedded in another document, stsFailed will be returned even if its embeddor is within 
an inbox/outbox section. 



msglOBXDocInlOBox 

Checks if a document is in a section in the Inbox/Outbox notebook. 

Takes P_IOBX_DOC_IN_IOBOX, returns STATUS. Category: class message. 

#define msglOBXDocInlOBox MakeMsg(clsIOBXService, 3) 

uments typedef struct IOBX_DOC_IN_IOBOX { 

ANM_AUX_NOTEBOOK notebook; //In: Which notebook? 

UUID uuid; // In: document uuid 

CLASS svcClass; // In: service class to check for 

} IOBX_DOC_IN_IOBOX, *P_IOBX_DOC_IN_IOBOX; 

Messages Sent to an Outbox Service 
Instance 

msglOBXSvcMovelnDoc 

Moves a document into the outbox section. 

Takes P_IOBXSVC_MOVE_COPY_DOC, returns STATUS. 

#define msglOBXSvcMovelnDoc MakeMsg(clsIOBXService, 4) 

wmenfs typedef struct IOBXSVC_MOVE_COPY_DOC { 

ANM_AUX_NOTEBOOK notebook; // In: Which notebook? 
FS_LOCATOR source; // In: Location of source document. 

U16 sequence; // In: Sequence number to move/copy 

// in front of. 

} IOBXSVC_MOVE_COPY_DOC, *P_IOBXSVC_MOVE_COPY_DOC; 

mtmnts Superclass behavior is to move the document located at pArgs->source into the input/output queue 

associated with the inbox/outbox service. For example, set pArgs->sequence to 1 to move the document 
to the top of the queue. Set it to maxU16 to move the document to the bottom of the queue. 

After the document is moved (or copied) to the input/output queue, it is considered to be in a state 
ready for input/output, even though the service may not be connected at the time. Client should not 
alter the document in any way once it has been moved to the input/output queue. 

Subclasses can provide their own behavior if they wish. Remember to use the class message 
msglOBXSvcSwitchlcon to change the inbox/outbox icon. 

msglOBXSvcCopylnDoc 

Copies a document into the Inbox/Outbox section. 

Takes P_IOBXSVC_MOVE_COPY_DOC, returns STATUS. 

#define msglOBXSvcCopylnDoc MakeMsg(clsIOBXService, 5) 
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Messoge typedef struct IOBXSVC_MOVE_COPy_DOC { 

Arguments ANM_AUX_NOTEBOOK notebook; // In: Which notebook? 

FS_LOCATOR source; // In: Location of source document. 

U16 sequence; // In: Sequence number to move/copy 

// in front of. 

} IOBXSVC_MOVE_COPY_DOC, *P_IOBXSVC_MOVE_COPY_DOC; 

Comments Same as msglOBXSvcMovelnDoc, except that the document is copied to the input/output queue. 



msglOBXSvcGetTempDir 

Passes back a handle for a temporary directory. 
Takes P_OBJECT, returns STATUS. 



>- 
I- 

#define msglOBXSvcGetTempDir MakeMsg(clsIOBXService, 6) > 



Comments This message is provided for cHents who may want to prepare their input/output document before 

moving it into the input/output queue. The handle of an "official" temporary directory is passed back 
and it can be used as temporary storage for documents, data, etc. Clients are responsible for deleting 
temporary files they created when done. This temporary directory will be flushed after a warm boot. 

msglOBXSvcPoUDocuments 

Polls all documents waiting for input/output. 

Takes nothing, returns STATUS. 

#define msglOBXSvcPoUDocuments MakeMsg(clsIOBXService, 7) 

This message tells the inbox/outbox service to look through its queue and initiate the input/output 
process for the first document ready to do so. The service will first make sure that it is enabled and is 
connected to the designated input/output port. If these conditions are met, it will then self-send 
msglOBXSvcNextDocument to locate the next document ready for input/output. 

If msglOBXSvcNextDocument returns stsOK, indicating that a document is ready, this message 
proceeds to self-send msglOBXSvcLockDocument to lock the document, and finally 
msglOBXSvcIOStart to initiate the input/output process. 

If msglOBXSvcNextDocument returns stsOBXSvcDocNotReady, indicating that the section is not 
empty but none of the documents are ready for input/output, this message self-sends 
msglOBXSvcScheduleDocument to schedule the document passed back in pArgs at a later time. 

Subclasses normally do not process this message. 

msglOBXSvcNextDocument 

msglOBXSvcNextDocument 

Passes back the next document ready for input/output. 

Takes P_IOBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msglOBXSvcNextDocument MakeMsg(clsIOBXService, 8) 

typedef struct IOBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 

} lOBXSVC DOCUMENT, *P lOBXSVC DOCUMENT; 
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Superclass behavior is to start from the top of the queue and locate the first document ready for 
input/output. If one is found, information about the document is passed back in pArgs. The same 
pArgs will be passed to messages msglOBXSvcLockDocument and msglOBXSvcIOStart. By default, a 
document is ready for input/output when it is closed. If the document is open, it will receive 
msglOBXDocIOStartOK and it should return stsOK to indicate that it is ready for input/output. 

Subclasses can provide their own behavior if they wish. Return stsOBXSvcSectionEmpty to give the 
superclass an opportunity to change the inbox/outbox icon from filled to empty. Or refresh the look of 
the icon by sending msglOBXSvcSwitchlcon to the service class. 

StsOK A document is ready for input/output. 

StsOBXSvcSectionEmpty The input/output queue is empty. 

stsOBXSvcDocNotReady No document in the input/output queue is ready. 

Service-Specific Error Returns. 

msglOBXSvcPollDocuments 



msglOBXSvcLockDocument 

Locks the document in preparation for input/output. 

Takes P_IOBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

#define msglOBXSvcLockDocument Ma]ceMsg(clsIOBXService, 9) 

typedef struct IOBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 

} IOBXSVC_DOCUMENT, *P_IOBXSVC_DOCUMENT; 

This message is a place holder for subclasses that may require additional preparatory work to be 
performed on a document before it is ready for input/output. For example, a document may have to be 
"locked" so that it can not be opened during the input/output process. This message may be used for 
other purposes as well. For example, an inbox/outbox service may decide to store a light-weight 
"shadow" document (e.g., a report designator for a database application) in the input/output queue 
until it is chosen for input/output. The service then handles this message by converting the shadow 
document to a real one (e.g., the actual report). 

The superclass behavior for this message is to stamp the document directory with the filesystem attribute 
iobxsvcDocIOInProgress. This stamp will prevent any gestures over the document from being 
processed. This means that once a document is locked for input/output it can not be deleted, renamed, 
etc. via gestures. 

msglOBXSvcUniockDocument 

msglOBXSvcUnlockDocument 

Unlocks a document that was previously locked. 

Takes P_IOBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

#define msglOBXSvcUnlockDocument MakeMsg(clsIOBXService, 10) 
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%essci 



typedef struct IOBXSVC_DOCUMENT { 

msnfs OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length ] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 

} IOBXSVC_DOCUMENT, *P_IOBXSVC_DOCUMENT; 

neRts This message is a place holder for subclasses that may require additional "cleanup" work to be 

performed on a document before it is put back to the input/output queue. 

The superclass behavior for this message is to remove the iobxsvcDocIOInProgress stamp on the 
document directory. 

liso msglOBXSvcLockDocument > 

u 

111 

z 
msglOBXSvcScheduleDocument o 

Schedules a document that is not ready for input/output 

Takes P_IOBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

#define msglOBXSvcScheduleDocument MakeMsg(clsIOBXService, 11) 



u 



lesssge typedef struct IOBXSVC_DOCUMENT { 

^rgunierifs OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length ] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} IOBXSVC_DOCUMENT, *P_IOBXSVC_DOCUMENT; 

eiTimerits This message is sent when msglOBXSvcNextDocument locates a document in the input/output queue 

but the document is not ready for input/output. 

Subclasses should provide their own behavior. The default behavior is to release the ownership of the 
target service (i.e., become disabled), with the expectation that the user must manually schedule the 
document later on (by re-enabling the section.) 

ee Also msglOBXSvcNextDocument 



msglOBXSvcIOStart 

Starts the input/output process for a document in the input/output queue. 

Takes P_IOBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

#define msglOBXSvcIOStart MakeMsglclsIOBXService, 12) 

typedef struct IOBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length ] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 

} IOBXSVC_DOCUMENT, *P_IOBXSVC_DOCUMENT; 

Superclass behavior is to activate the inbox/outbox document if it isn't already active, and then send 
msglOBXDocIOStart to the document instance. 

Subclasses can provide their own behavior if they wish. 
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Cancels the input/output process. 

Takes nothing, returns STATUS. 

#define msglOBXSvcIOCancel MalceMsg(clsIOBXService, 13) 

iiieofs This message is sent to the service when the caller wishes to cancel any input/output operation in 

progress. The service responds to this message by sending msglOBXDocOutuptCancel to an active 
inbox/outbox document. After the document is cancelled, the service will post an error note to the user 
if there are other documents waiting to be processed. The user then decides whether or not the service 
should proceed to send the remaining documents. 

Subclasses do not normally process this message. 

^ msglOB^Svcioae^^Up "^^''^"''^"^^^^^ 

Cleans up after the current input/output is done. 

Takes P_IOBX_DOC_OUTPUT_DONE, returns STATUS. Category: self-post.. 

#define msglOBXSvcIOCleanUp MakeMsg(clsIOBXService, 14) 

imenfs Enum32 (IOBX_DOC_EXIT_BEHAVIOR) { // What to do after a document 

// is processed 

iobxDocExitDoNothing = 0, 

iobxDocExitDelete =1, 

iobxDocExitMarkAsFailed = 2, 

iobxDocExitMarkAsCancelled = 3 
}; 
typedef struct IOBX_DOC_OUTPUT_DONE { 

IOBX_DOC_EXIT_BEHAVIOR behavior; // exit behavior 

P_UNKNOWN pDocData; // Unused: document specific data 

} IOBX_DOC_OUTPUT_DONE, *P_IOBX_DOC_OUTPUT_DONE ; 

nients This message is posted to self as a result of the service receiving msglOBXDocIODone, which is sent by 

the inbox/outbox document when it finishes the input/output operation. The inbox/outbox document 
will be either deleted or marked as specified in pArgs, and when everything is properly cleaned up the 
service will post msglOBXSvcPoUDocuments to self to see if anything else is waiting for input/output. 

Subclasses do not normally process this message. 

Aiso msglOBXDocIODone 

msglOBXSvcStateChanged 

Tells observers that the service state just changed. 
Takes OBJECT, returns STATUS. Category: observer notification.. 
♦define msglOBXSvcStateChanged MakeMsg{clsIOBXService, 15) 

oieots Informs observers that the state of a service has just changed. pArgs is the UID of the service. 

msglOBXSvcQueryState 

Passes back the state of the service. 

Takes P_IOBXSVC_QUERY_STATE, returns STATUS. 

tdefine msglOBXSvcQueryState MakeMsg(clsIOBXService, 16) 
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Inbox/Outbox Document Messages 



typedef struct { 

BOOLEAN enabled; //is the service enabled? 

CHAR status [nameBufLength] ; // text describing the status of 

// the service. 

CHAR docName [nameBufLength] ; // document being processed 

P_UNKNOWN pStateData; // subclass' s private data 

} lOBXSVC QUERY STATE, *P lOBXSVC QUERY STATE; 



msglOBXSvcGetEnabled 

Gets the enabled state of the service. 

Takes P_BOOLEAN, returns STATUS. 

#define msglOBXSvcGetEnabled MakeMsg(clsIOBXService, 17) ^ 

Subclasses can override this message and redefine the notion of "enabled." The default behavior of the ^ 

superclass is to equate "enabled" with the ownership of the target service (i.e., input/output device). z 

That is, the service is "enabled" when it owns the target service. By appending to or replacing the default 
behavior, a subclass can define additional conditions which must be met before a service is considered 
enabled. 

msglOBXSvcSetEnabled 

Sets the enabled state of the service. 

Takes BOOLEAN, returns STATUS. 

#define msglOBXSvcSetEnabled MakeMsg{clsIOBXService, 18) 

This message is sent to the service in response to service notification messages msgSvcOwnerAcquired 
and msgSvcOwnerReleased. Subclasses can provide their own behavior and thereby redefine the notion 
of "enabled" for the service. If they do, they must pass this message up to the ancestor so that observers 
of the inbox/outbox service will be properly notified. 



Inbox/Outbox Document Messages 



msglOBXDocIOStartOK 

Asks the inbox/outbox document if it is OK to start the input/output process 

Takes nothing, returns STATUS. 

tdefine msglOBXDocIOStartOK MakeMsg{clsIOBXService, 19) 

When an inbox/outbox service finds an opened document in the inbox/outbox section, it sends this 
message to the document instance, asking whether it's OK to start the input/output operation while the 
document remains open. When the document receives this message, it should return stsOK to give the 
service permission to begin the input/output process. An error status, including stsNotUnderstood, is 
taken to mean that the document instance vetos the request and the service will not start the 
input/output process. 

msgIOB3a5ocf6st^^ ..^.........^ ,.... 

Tells an inbox/outbox document to start the input/output process. 

Takes nothing, returns STATUS. 

tdefine msglOBXDocIOStart MakeMsg(clsIOBXService, 20) 
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Comments This message is sent by the inbox/outbox service to a document. The document should respond to this 

message by starting the input/output process. 

msglOBXDocIODone 

Tells the inbox/outbox service that input/output is finished. 

Takes P_IOBX_DOC_OUTPUT_DONE, returns STATUS. Category: client responsibility. 

#define msglOBXDocIODone MakeMsg(clsIOBXService, 21) 

Messogs typedef struct IOBX_DOC_OUTPUT_DONE { 

Arguments IOBX_DOC_EXIT_BEHAVIOR behavior; // exit behavior 

P_UNKNOWN pDocData; // Unused: document specific data 

} IOBX_DOC_OUTPUT_DONE, *P_IOBX_DOC_OUTPUT_DONE ; 

Coriimerifs When the input/output process is finished, the inbox/outbox document in charge of the input/output 

should send this message to the inbox/outbox service. This message must be sent even if the 
input/output process has been aborted. The pArgs for this message tells the inbox/outbox service what 
to do with the inbox/outbox document. If obxDocExitDelete is specified, the document will be 
removed from the inbox/outbox. In all other cases the document will be unlocked and left in the 
inbox/outbox. If either obxDocExitMarkAsCancelled or obxDocExitMarkAsFailed are specified, the 
name of the document will be altered to provide visual indication for the user that the input/output 
process has not completed successful]^. 

See Mm msglOBXDocGetService 

msglOBXDocIOCancel 

Tells an inbox/outbox document to cancel the input/output process. 

Takes nothing, returns STATUS. 

#define msglOBXDocIOCancel MakeMsg(clsIOBXService, 22) 

Comments This message is used by the inbox/outbox service to inform a document that it should cancel the 

input/output process. The document should handle this message by terminating its input/output 
operation and then sending msglOBXDocIODone to the service with pArgs->behavior set to 
obxDocExistMarkAsCanceiled. 

msglOBXDocStatusChanged 

Tells the inbox/outbox service that the document status is changed. 

Takes P_IOBX_DOC_STATUS_CHANGED, returns STATUS. Category: client responsibility. 

#define msglOBXDocStatusChanged MakeMsg(clsIOBXService, 23) 

Arguments typedef Struct IOBX_DOC_STATUS_CHANGED { 

CHAR status [nameBuf Length] ; // Text describing document state 

P_UNKNOWN pDocData; // Unused: document-specific data 

} IOBX_DOC_STATUS_CHANGED, *P_IOBX_DOC_STATUS_CHANGED ; 

£ This message is sent by the inbox/outbox document to the service whenever its status has just changed. 

This status is displayed on Status column for the inbox/outbox section, in the Inbox/Outbox notebook. 
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Link layer API definition. 

This file contains the interface definition for link layer protocols. 

1. Link layer protocols must sub-class clsLink. 

2. clsLink sub-classes cIsService, 

#ifndef LINK_INCLUDED 
tdefine LINK_INCLUDED 
typedef struct 



{ 

U16 

U8 
} ADDRESS, *P ADDRESS; 



addrSize; // size of address pointed to 
addr[8]; // address 



The PROTOCOL_ADDRESS structure contains all the addressing information needed below the transport 
level. Unspecified addresses have null pointers. 



typedef struct { 

} PROTOCOL ADDRESS, * 



P PROTOCOL ADDRESS; 



The PROTOCOL_INFO structures in the transmit and receive descriptors holds the following 
information. 



typedef struct { 

PROTOCOL_ADDRESS 

PROTOCOL_ADDRESS 
} PROTOCOL_INFO; 

tdefine sizeRxBuf 608 
typedef struct RXBUFDESC { 

PROTOCOL_INFO 
} RX_DESC, *P_RX_DESC; 

typedef struct { 

U16 

U8 
} BLOCK, *P_BLOCK; 

#define InkMaxBlocks 8 
tdefine sizeTxImmedData 32 

typedef struct { 

PROTOCOL_INFO 

BLOCK 

U8 
} TX_DESC, *P_TX_DESC; 

tdefine stsNoTxBuffer 
#define stsNoRxBuffer 
tdefine stsTxCollisionOrDefer 
tdefine stsTxTimeout 



src; 
dest; 



info; 



blockLen; 
*pBlock; 



info; 

txBlockTab [InkMaxBlocks] ; 
inraiedData [sizeTxImmedData] ; 

MakeStatus (clsLink, 1) 

MakeStatus (clsLink, 2) 

MakeStatus (clsLink, 3) 

MakeStatus (clsLink, 4) 



// A power cycle has happened, the link should be closed and reinitialized 
tdefine stsLinkPowerCycle MakeStatus (clsLink, 5) 

// The link cable is not connected. 

tdefine stsLinkNot Connected MakeStatus (clsLink, 6) 

typedef U16 LINK PROTOCOL TYPE; 
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typedef enum 

{ 

linkMult least = flagO, 
linkBroadcast = flagl, 
linkPromiscuous = flag2, 
linkLoopback = flag3 

} LINK_SERVICES; 

typedef struct 
{ 

U16 tableSize; 

U8 linkAddress[2]; 
} *P_BROADCAST_ADDR, *P_MULTICAST_ADDR; 

typedef struct 
{ 



// multicast transmit and receive 
// broadcast transmit and receive 
// promiscuous receive mode 
// loopback of transmit to receive 



U16 
U8 



tableSize; // size of link Attributes table 
typeName[32] ; // ASCIIZ name of LINK type: LocalTalk, Ethernet 
// ASYNC, SDLC, etc. 
// length In bytes of link addresses 
// current link address of local station 
// link communication speed in bits per second 
// maximum amount of data that will fit in a link frame 
// maximum size of a link frame (including link header) 
// total number of available link buffers for this 



linkAddrLen; 

llnkAddr[16]; 

linkSpeed; 

maxDataSize; 

maxFrameSize; 

numBuffers; 

linkServices; 
broadcast; 
pMult IcastTable ; 



U16 

U8 

U32 

U16 

U16 

U16 
device 

LINK_SERVICES 

ADDRESS 

P_MULTICAST_ADDR 

// add additional fields here 
} LINK_ATTRIBUTES, *P_LINK_ATTRIBUTES; 
typedef enum 
{ 

linkOperat lonal , 

llnkHardwareFallure, 

linkConfigurationFailure, 

llnkHardwareNot Installed 
} LINK_OPERATING_STATUS; 
typedef struct 
{ 

LINK_OPERATING_STATUS llnkStatus ; 

// additional specific status info goes here 
} LINK_STATUS, *P_LINK_STATUS; 
typedef void (EXPORTED * PF_PROTOCOL_HANDLER) (P_RX_DESC) ; 

Structure of the link header 



// LINK services supported 
// broadcast address 

// pointer to multicast address table 



#pragma pack(l) 
typedef struct 
{ 

US 

US 

US 
} LINK_HEADER, 
tpragma pack() 

#define maxRxFrameSize sizeRxBuf 

typedef struct TX_FRAME 

{ 

struct TX_FRAME 

BOOLEAN 

U16 

U32 

unsigned char 
} TX_FRAME, *P_TX_FRAME; 

#deflne InkMaxShortFrameSize 10 



// byte boundary packing for protocol headers 



destLlnkAddr; 
srcLlnkAddr; 
typeLlnk; 
*P_LINK_HEADER; 
// back to command line stuff 



link; 
sent; 
length; 
physAddr; 
buf [maxRxFrameSize] ; 
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typedef struct SHORT_TX_FRAME 

{ 

struct SHORT_TX_FRAME * link; 

BOOLEAN sent; 

U16 length; 

U32 physAddr; 

unsigned char buf [InkMaxShortFrameSize] ; 
} SHORT_TX_FRAME, *P_SHORT_TX_FRAME; 

msgLINKInstallProtocol 

Install a link layer protocol handler to receive frames. 

Takes P_INSTALL_PROTOCOL, returns STATUS. 

tdefine msgLINKInstallProtocol MakeMsg( clsLink, 1 ) > 

typedef struct INSTALL_PROTOCOL{ 2 

LINK_PROTOCOL_TyPE linkProtocolType; g 

PF_PROTOCOL_HANDLER pNewHandler; 8 

} INSTALL_PROTOCOL, * P_INSTALL_PROTOCOL; 

msgLINKRemoveProtocol 

Remove a link layer protocol handler. 

Takes P_REMOVE_PROTOCOL, returns STATUS. 

tdefine msgLINKRemoveProtocol MakeMsg( clsLink, 2 ) 

typedef struct REMOVE_PROTOCOL { 

LINK_PROTOCOL_TYPE linkProtocolType ; 
} REMOVE_PROTOCOL, * P_REMOVE PROTOCOL; 

msgLINKTransmit 

Transmit a packet. 

Takes P_LINK_TRANSMIT, returns STATUS. 

tdefine msgLINKTransmit MakeMsg( clsLink, 5 ) 

typedef struct LINK_TRANSMIT { 

P_TX_DESC pTD; 

} LINK TRANSMIT, * P LINK TRANSMIT; 



msgLINKBufferReturn 

Return receive buffer to the link layer. 

Takes P_BUFFER_RETURN, returns STATUS. 

tdefine msgLINKBufferReturn MakeMsg( clsLink, 6 ) 

typedef struct BUFFER_RETURN { 

P_RX_DESC pRD; 

} BUFFER RETURN, * P BUFFER RETURN; 



msgLINKAttributesGet 

Obtain the link layer attributes. 

Takes P_ATTRIBUTES_GET, returns STATUS. 

tdefine msgLINKAttributesGet MakeMsg( clsLink, 7 ) 
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typedef struct ATTRIBUTES_GET { 

P_LINK_ATTRIBUTES pAttributes, 

} ATTRIBUTES GET, * P ATTRIBUTES GET; 



msgLINKStatusGet 

Obtain the link layer statistics. 

Takes P_SrATUS_GET, returns STATUS. 

#define msgLINKStatusGet MakeMsg( clsLink, 8 ) 

typedef struct STATUS_GET { 

P_LINK_STATUS pStatus; 

} STATUS_GET, * P_STATUS_GET; 

msgLINKAddressAcquire 

Acquire the link layer address. 

Takes P_ADDRESS_ACQUIRE, returns STATUS. 

tdefine msgLINKAddressAcquire MakeMsg( clsLink, 9 ) 

typedef struct ADDRESS_ACQUIRE { 

U16 linkAddrLen; // length in bytes of link addresses 

U8 linkAddr[16] ; // current link address of local station 

BOOLEAN server; // acquire a server address 

} ADDRESS ACQUIRE, * P ADDRESS ACQUIRE; 







MODEM.H 



This file contains the API for clsModem. 

clsModem inherits from clsService. 

clsModem provides the interface a client uses to communicate via a modem. The modem service is 
located, bound to, opened, and closed via standard PenPoint service messages. 

The object which opens a modem service becomes its client. After opening a modem service, it is 
recommened that a client explicitly reset the modem firmware, initialize the modem I/O port settings, 
and then set the modem firmware to the desired state. 

The modem firware is reset by sending msgModemReset to an open modem service. Refer to 
msgModemReset below for a description of the state to which the modem firmware is reset. 

A client obtains current modem I/O port settings by sending msgSioGetMetrics to a modem service. 
I/O port settings may be altered by sending msgSioSetMetrics to the modem service. These messages in 
addition to msgSioInit, msgSioBreakSend, msgSioControlInStatus, msgSioInputBufFerStatus, and 
msgSioInputBufferFlush are the only clsMILAsyncSIODevice messages which clsModem handles. 
Refer to file "sio.h" for a description of these messages. 

After initializing the modem I/O port, a client may then send clsModem messages to initialize the 
modem to a desired state. Such initialization may be accomplished via discrete messages, or via 
msgSvcSetMetrics. 

Upon successfiilly initializing a modem, the client may then establish a connection, transmit data and/or 
receive data via the connection, and finally terminate the connection. Clients send clsStream messages 
to read/write data from/to the modem. Refer to file "stream.h" for a description of clsStream messages. 

**** PLEASE NOTE **** 

In a fiiture release of PenPoint, the clsModem API will be augmented. Compatibility with the 
clsModem API described herein shall be maintained for at least one release. 

Defined within this header file for the clsModem API 



Defines and Typedefs 



S«e Aisc 



service. n , stream.h . 

#ifndef MODEM_INCLUDED 
tdefine MODEM_INCLUDED 

#ifndef GO_INCLUDED 

♦include <go.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

#endif 

tifndef SERVICE_INCLUDED 

finclude <service.h> 

tendif 

tifndef UID_INCLUDED 

tinclude <uid.h> 

#endif 

# i f nde f D I ALENV_INCLUDED 

tinclude <dialenv.h> 

tendif 
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Observer Notification Messages 

msgModemActivity 

Notification sent to observers signifying changes in modem activity. 

Takes MODEM_ACTIVITY, returns N/A. Category: observer notification. 

#define msgModemActivity MakeMsg(clsModein, 1) 

The current modem activity/state. 
Modem service has been opened for use. * 
Currently being reset. 
Dialing a phone number. * 
Awaiting a connection/answer. 
Connected with remote node. * 
Negotiating session/link parms . 
Sending data. 
Receiving data. 
Answering a call. * 
Terminating the connection. * 
Connection terminated. * 
Modem service has been closed. * 
* = required notifications . 

NOTE: A modem service needn't implement all observer notifications listed below. Those marked with 
an asterik are the required minimum. 



Enum32 (MODEM_ACTIVITY) { 


// 


mdmOpened, 


// 


mdmResetting, 


// 


mdmDialing, 


// 


mdmAwaitingConnection, 


// 


mdmConnected, 


// 


mdmNegotiating, 


// 


mdmS ending, 


// 


mdmReceiving, 


// 


mdmAnswering, 


// 


mdmHangingUp, 


// 


mdmDisconnected, 


// 


mdmClosed 


// 


}; 


// 



Client Notification Messages 



msgModemResponse 

Provides the modem's response to a command. 

Takes MODEM_RESPONSE_INFO, returns N/A. Category: client notification. 

tdefine msgModemResponse MakeMsg(clsModem, 2) 



Enum32 {MODEM_RESPONSE) { 
mdmResOK, 

mdmResUnrecognized, 
mdmResError, 
mdmResNoCarrier, 
mdmResNoDialTone , 
mdmResPhoneBusy, 
mdmResNoAnswer, 
mdmResInvalidFrame , 
mdmResCRCError, 
mdmResRing, 
mdmResConnect , 
mdmResConnect300 , 
mdmResConnect600, 
mdmResConnectl200, 
mdmResConnect2400, 
mdmResConnect4800, 
mdmResConnect 9600, 
mdmResConnectl9200, 
mdmResConnectReservedOl , 
mdmResConnectReserved02 , 
mdmResConnectReservedOS , 
mdmResConnectMNP , 
mdmResConnectl200MNP, 
mdmResConnect 2 4 OMNP , 
mdmResConnectl200LAPM, 
mdmResConnect 2 4 OLAPM, 
mdmResConnectReserved04 , 
mdmResConnectReservedOS , 



// Modem response indications. 

// OK - command accepted. 

// Error - Unrecognized response from modem. 

// Error - Error response from modem. 

// Error - No line carrier detected. 

// Error - No phone dial tone detected. 

// Error - Phone line busy signal detected. 

// Error - No one answered at the other end. 

// Error - Invalid frame detected. 

// Error - Cyclic redundancy check error. 

// Ring indication signal detected. 

// Connection established. 

// 300 baud connection established. 

// 600 baud connection established. 

// 1200 baud connection established. 

// 2400 baud connection established. 

// 4800 baud connection established. 

// 9600 baud connection established. 

// 19200 baud connection established. 

// Reserved for future expansion. 

// Reserved for future expansion. 

// Reserved for future expansion. 

// MNP connection has been established. 

// 1200 baud MNP connection established. 

// 2400 baud MNP connection established. 

// 1200 baud LAPM connection established. 

// 2400 baud LAPM connection established. 

// Reserved for future expansion. 

// Reserved for future expansion. 
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mdmResConnectReservedOe // Reserved for future expansion. 

}; 
tdefine mdmSizeMaxResponse 63 

typedef struct { // Modem response information. 

U8 symbols [mdmSizeMaxResponse+1] ;// Symbols comprising a response. 

MODEM_RESPONSE response; // Response meaning as enumerated above. 

U32 spare; // Reserved for future expansion. 

} MODEM_RESPONSE_INFO, *P_MODEM_RESPONSE_INFO; 

Comments Provides the response to a previous modem request/command. msgModemReponse is only sent to the 

modem service's client if the response behavior has been set to mdmResponseViaMessage (RE: 
msgModemSetResponseBehavior) . 

If a desired response isn't available, then please contact GO Corporation to see that it gets added as a w. 

standard modem response. Thank you. > 



NOTE: The modem service depends upon the order in which the responses are defined. 

msgModemConnected 

Notification sent to the client indicating the modem has connected with a remote node modem. 

Takes nothing, returns N/A. Category: client notification. 

tdefine msgModemConnected MakeMsg(clsModem, 3) 

A client may obtain information regarding the connection via msgModemGetConnectionlnfo. 

msgModemDisconnected 

Notification sent to the client indicating that the current connection has been terminated. 
Takes nothing, returns N/A. Category: client notification, 
tdefine msgModemDisconnected MakeMsg(clsModem, 4) 



msgModemRingDetected 

Notification sent to the client indicating that a ring indication has been received from the modem. 
Takes nothing, returns N/A. Category: client notification, 
tdefine msgModemRingDetected MakeMsg(clsModem, 5) 

msgModemTransmissionError 

Notification sent to the client indicating that an error has been detected during transmission (sending or 
receiving) of data. 

Takes nothing, returns N/A. Category: client notification. 

tdefine msgModemTransmissionError MakeMsg(clsModem, 6) 

This unsolicited message is typically sent as a result of detecting a data framing error, or other low-level 
modem link protocol generated error condition. 

msgModemErrorDetected 

Notification sent to the client indicating that an unexpected error indication has been received from the 
modem. 

Takes nothing, returns N/A. Category: client notification, 
tdefine msgModemErrorDetected MakeMsg(clsModem, 7) 
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Action Messages 



msgModemSetResponseBehavior 

Set the modem response mode, and command-to-response time-out values. 

Takes P_MODEM_RESPONSE_BEHAVIOR, returns STATUS. Category: modem service request. 

tdefine msgModemSetResponseBehavior MakeMsg(clsModem, 16) 

Enum32 (MODEM_RESPONSE_MODE) { // Mode for conveying modem responses. 

mdmResponseViaStatus, // Report via status (Default) . 

mdmResponseViaMessage, // Report via notification msgModemResponse . 

mdmResponseTransparent // Don't intercept and process modem responses. 

}; 

Idefine mdmDefaultCommandTimeout 2500 // 2 1/2 second command timeout. 

#define mdmDefaultConnectTimeout 30000 // 30 second connect timeout. 

typedef struct { // Command-to-response timeouts. 

OS_MILLISECONDS timeoutCommand; // Timeout for all commands 

// except connect requests 

// (default of 2 1/2 seconds) . 

OS_MILLISECONDS timeoutConnect; // Timeout for connect requests 

// (default of 30 seconds) . 
} MODEM_TIMEOUT, *P_MODEM_TIMEOUT; 

typedef struct { // Modem command-response handling behavior. 

MODEM_RESPONSE_MODE mode; // Mode for coveying responses 

MODEM_TIMEOUT timeout;// Command-to-response timeouts. 

} MODEM_RESPONSE_BEHAVIOR, *P_MODEM_RESPONSE_BEHAVIOR; 

Response mode mdmResponseViaStatus causes the modem service to block and await a response from 
the modem. If the modem doesn't return a response within the specified time-out duration, stsTimeOut 
is returned. 

Response mode mdmResponseViaMessage is useful for clients that wish to ObjectPostAsync their 
modem service requests, and hence not block until completion (or timeout) of the request. Modem 
responses are reported to the client via msgModemResponse. 

Response mode mdmResponseTransparent disables the modem service response processing sub-system. 
Modem command responses are left unaltered within the input data stream. The client assumes 
responsibility for processing modem responses. All commands successftiUy sent to the modem return a 
status of stsOK. 

NOTE: Once a client switches to transparent mode (or sends modem register altering commands via 
msgModemSendCommand) they are responsible for the integrity of cIsModem. Therefore, it is the 
client's responsibility to ensure that the clsModem (and the modem) are reset to a known state upon 
switching from transparent mode to a different response mode. 

msgModemGetResponseBehavior 

Passes back the current modem response mode, and the current command-to-response time-out values. 
Takes P_MODEM_RESPONSE_BEHAVIOR, returns STATUS. Category: modem service request, 
tdefine msgModemGetResponseBehavior MakeMsg (clsModem, 17) 

typedef struct { // Modem command-response handling behavior. 

MODEM_RESPONSE_MODE mode; // Mode for coveying responses 

MODEM_TIMEOUT timeout;// Command-to-response timeouts. 

} MODEM RESPONSE BEHAVIOR, *P MODEM RESPONSE BEHAVIOR; 
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msgModemSendCommand 

Sends a specified command to the modem. 

Takes P_MODEM_SEND_COMMAND, returns STATUS. Category: modem service request. 

tdefine msgModemSendCoiranand MakeMsg(clsModem, 18) 

#define mdmSizeMaxCommand 80 // Max command size is 80 bytes. 

irgymenfs typedef struct { 

P_U8 pCmdStr; // In: Ptr to command string 

// (null terminated) . 

OS_MILLI SECONDS timeout; // In: Timeout for cmd response. 

MODEM_RESPONSE_INFO responselnfo; // Out: The response to the cmd. 

} MODEM_SEND_COMMAND, *P_MODEM_SEND_COMMAND ; >_ 



The timeout value specified within MODEM_SEND_COMMAND supersedes that specified via 
msgModemSetResponseBehavior. 

-x,.v,v.wxxx^wxv.^„»x...cc.x« .w ^..w..x. XX.V.V.WX. C.W..W..O ^.xc.vc...c.u.x^ v.c O 

the clsModem API described herein 



NOTE: Clients that send commands that alter modem registers are responsible for the integrity of 
clsModem. Therefore, it is the client's responsibility to ensure that such commands will not adversely 
affect clsModem. 

msgModemGetConnectionlnfo 

Passes back information about the current connection. 

Takes P_MODEM_CONNECTION_INFO, returns STATUS. Category: modem service request. 

tdefine msgModemGetConnectionlnfo MakeMsg (clsModem, 19) 

Enum32 (MODEM_CONNECTION) { // The type of connection established. 

mdmConnectionNone, // None; Disconnected. 

mdmConnectionStandard, // Standard data. 

mdmConnectionMNP, // MNP. 

mdmConnectionLAPM // LAPM. 

}; 
Enum32 (MODEM_LINK_CONTROL) { // Link and error control protocols. 

mdmLinkControlMNPClassl_4 = flagO, // MNP Levels 1 through 4. 

mdmLinkControlMNPClassS = flagl, // MNP Level 5 data compression. 

mditiLinkControlMNPClass6 = flag2, // MNP Level 6. 

mdmLinkControlMNPClass7 = flag3, // MNP Level 7 data compression. 

mdmLinkControlV42 = flag4, // Physical level error detection and 

// correction (LAPM link control) . 

mdmLinkControlV42bis = flag5 // V42 data compression. 
}; 
typedef struct { // Information about a connection. 

MODEM_CONNECTION connection; // The type of connection. 

MODEM_LINK_CONTROL linkControl; // Link control in use, if any/known. 

S32 baudRate; // Baud rate of connection. 

U32 spare [2]; // Reserved for future expansion. 

} MODEM_CONNECTION_INFO, *P_MODEM_CONNECTION_INFO; 

msgModemReset 

Resets the modem firmware, I/O port, and service state. 

Takes nothing, returns STATUS. Category: modem service request. 

tdefine msgModemReset MakeMsg (clsModem, 20) 
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:ommetits NOTE: The modem I/O port baud rate is reset to the highest supported data mode baud rate. 

Therefore not all implementations will reset the baud rate to 2400. The client may elect to subseqently 
change the baud rate for auto- baud detecting modems. 

Reset I/O port state: 

baud = 2400; 

line.dataBits = sioEightBits; 

line.stopBits = sioOneStopBit; 

line. parity = sioNoParity; 

controlOut .rts = true; 

controlOut.dtr = true; 

f lowChar . xonChar = 0x11; 

flowChar.xoffChar = 0x13; 
flowType.flowControl = sioNoFlowControl; 

Reset modem firmware state: 

Speaker control on until carrier detected (*) .volume medium (*). detection enabled (*). detection enabled 
(*).mode from dialing environment. disabled. on ring zero.character echo disabled. command result 
codes.verbal result codes (words). carrier upon connect.code + (ASCII 43). termination code carriage 
return (ASCII 13). 

(*) or set as per current modem option card setting. 

msgModemOffHook 

Picks up the phone line. 

Takes nothing, returns STATUS. Category: modem service request. 

#define msgModemOffHook MakeMsg(clsModem, 21) 

msgModemOnline 

Forces the modem online into data mode. 

Takes nothing, returns STATUS. Category: modem service request. 

tdefine msgModemOnline MakeMsg(clsModem, ,22) 

msgModemSetDialType 

Establishes the mode for dialing telephone numbers. 

Takes MODEM_DIAL_MODE, returns STATUS. Category: modem service request. 

#define msgModemSetDialType MakeMsg(clsModem, 23) 

Irgyiiieiifs Enum32 (MODEM_DIAL_MODE) { // Mode in which the modem is to dial. 

mdmPulseDialing, // Perform pulse dialing. 

mdmTouchtoneDialing, // Peform touch-tone dialing. 

mdmDialStringDialing, // Client supplies the dialing mode 

// embedded within the dialString. 

mdmDialingEnvironmentDialing// If available, use the current dialing 

// environment dialing mode, otherwise use 

// current modem firmware dialing mode (Default) . 
}; 
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msgModetnDial 

Performs dialing and attempts to establish a connection. 

Takes P_MODEM_DIAL, returns STATUS. Category: modem service request. 

tdefine msgModemDial MakeMsg(clsModem, 24) 

krgumems typedef struct { // Dialing and connection type. 

DIALENV_DIAL_STRING dialString; // In: Phone number to dial. 

U32 spare [2]; // Reserved for future expansion. 

} MODEM DIAL, *P MODEM DIAL; 



msgModemSetAutoAnswer 



Disables or enables the modem auto-answer feature. ^ 

I- 

Takes P_MODEM_SET_AUTO_ANSWER, returns STATUS. Category: modem service request. z 

#define msgModemSetAutoAnswer MakeMsg(clsModem, 25) 8 

krgumenis Enum32 (MODEM_AUTO_ANSWER) { // Modem auto-answer capability. 

mdmAutoAnswerDisabled, // Disable auto-answer (Default) . 

mdmAutoAnswerEnabled // Enable auto-answer. 
}; 

typedef struct { // Auto-answer settings. 

MODEM_AUTO_ANSWER autoAnswer; // In: Enable/disable auto-answer. 

S32 rings; // In: Number of rings before answer. 

} MODEM_SET_AUTO_ANSWER, *P_MODEM_SET_AUTO_ANSWER; 

:omments NOTE: For some modems a value of for rings disables auto-answ^er. 

msgModemSetAnswerMode 

Filters the type of calls to answer and connection reporting. 

Takes MODEM_ANSWER_MODE, returns STATUS. Category: modem service request. 

tdefine msgModemSetAnswerMode MakeMsg(clsModem, 26) 

Irgyments Enum32 {MODEM_ANSWER_MODE) { // Modem answer filter/mode. 

mdmAnswerDataMode = flagO, // Answer in data mode. 

mdmAnswerFaxMode = flagl, // Answer in fax mode. 

mdmAnswerVoiceMode = flag2 // Answer in voice mode. 
}; 

Comments NOTE: Not all modems are capable of discriminating between the type of incoming call. 



msgModemAnswer 

Immediately answers a telephone call. 

Takes nothing, returns STATUS. Category: modem service request. 

tdefine msgModemAnswer MakeMsg(clsModem, 27) 

msgModemHangUp 

Hang-ups and disconnects to terminate a connection. 

Takes nothing, returns STATUS. Category: modem service request. 

tdefine msgModemHangUp MakeMsg{clsModem, 28) 
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msgModemSetSignallingModes 

Establishes/restricts the modem to use specific signalling modes/standards. 

Takes P_MODEM_SIGNALLING_MODES, returns STATUS. Category: modem service request. 

tdefine msgModemSetSignallingModes MakeMsg(clsModem, 29) 



Enum32 (MODEM SIGNALLING VOICEBMD) { 



mdmVoiceBandBelllOSJ 


= flagO, 


// 


mdinVoiceBandBell212A 


= flagl. 


// 


mdmVoiceBandV21 


= flag2, 


// 


mdmVoiceBandV22 


= flags, 


// 
// 


mdmVoiceBandV22bis 


= flag4, 


// 
// 


mdmVoiceBandV23 


= flags, 


// 


mdinVoiceBandV2 6 


= flag6, 


// 
// 


mdmVoiceBandV2 6bis 


= flag?. 


// 


mdmVoiceBandV2 6ter 


= flags. 


// 
// 


mdmVoiceBandV27 


= flag9. 


// 


mdmVoi ceBandV2 7bi s 


= flaglO, 


// 


mdinVoiceBandV27ter 


= flagl 1, 


// 


mdmVoiceBandV29 


= flagl2, 


// 
// 


mdinVoiceBandV32 


= flagl 3, 


// 
// 


mdmVoiceBandVSS 


= flagl4 


// 
// 



}; 

Enum32 (MODEM_SIGNALLING_WIDEBAND) { 
mdmWideBandV35 = flagO, 



mdmWideBandV3 6 



mdmWideBandV37 



flagl, 
flag2 



// Voice-band signalling standards. 
300 BPS. 
1200 BPS. 

300 BPS duplex modem on GSTN. 
1200 BPS duplex modem on GSTN 

or P-P leased two-wire circuits. 
2400 BPS duplex modem on GSTN 

or P-P two-wire leased circuits . 
600/1200 BPS modem on GSTN. 
2400 BPS modem on four-wire 

leased circuits . 
2400/1200 BPS modem on GSTN. 
2400 BPS duplex modem on GSTN 

or P-P two-wire leased circuits. 
4800 BPS on leased circuits. 
2400/4800 BPS on leased circuits. 
4800/2400 BPS modem on GSTN. 
9600 BPS FDX or HDX modem on 

P-P four-wire leased circuits. 
9600/4800 BPS duplex modem on 

GSTN or leased circuits. 
14400 BPS modem on P-P 

four-wire leased circuits. 

// Wide-band signalling standards. 

// 48 KBPS data transmission on 

// 60-108 KHz group band circuits. 

// 48-72 KBPS sync data transmission 

// on 60-108 KHz group band circuits, 

// 72-168 KBPS sync data transmission 

// on 60-108 KHz group band circuits, 



Its 



}; 

typedef struct { // Modem modulation/signalling modes, 

MODEM_SIGNALLING_VOICEBAND voiceBand; // Voice band signalling. 

MODEM_SIGNALLING_WIDEBAND wideBand; // Wide band signalling. 
} MODEM_S IGNALLING_MODES , *P_MODEM_S IGNALLING_MODES ; 

NOTE: Not all modems provide support for selecting signalling modes. 



msgModemSetToneDetection 

Enables or disables busy tone and/or dial tone detection. 

Takes MODEM_TONE_DETECTION, returns STATUS. Category: modem service request. 

tdefine msgModemSetToneDetection Ma]ceMsg(clsModem, 30) 

Enum32 (MODEM TONE DETECTION) { // Busy and dial toneCarrier signal on/off. 



mdmToneDetectDisable , 
mdmToneDetectBusyOnly, 
mdmToneDetectDialOnly, 
mdmToneDetectBusyAndDial 



// Detect neither busy tone or dial tone. 

// Detect busy tone, but not dial tone. 

// Detect dial tone, but not busy tone. 

// Detect dial tone and busy tone (Default) 



}; 
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msgModemSetSpeakerControl 

Enables, disables and controls modem speaker behavior. 

Takes MODEM_SPEAKER_CONTROL, returns STATUS. Category: modem service request. 

#define msgModemSetSpeakerControl MakeMsg(clsModem, 31) 

Enum32 (MODEM_SPEAKER_CONTROL) { // Specifies the modem speaker behavior. 

mditiSpeakerOn, // Speaker is always on. 

mdmSpeakerOff, // Speaker is always off. 

mdmSpeakerOnConnectOff // Speaker on until carrier detected (Default) 
}; 



msgModemSetSpeakerVoluine 



> 

Sets the volume of the modem speaker. J^ 

z 
z 
o 

u 



Takes MODEM_SPEAKER_VOLUME, returns STATUS. Category: modem service request. 
#define msgModemSetSpeakerVolume MakeMsg(clsModem, 32) 

Enum32 (iyiODEM_SPEAKER_VOLUME) { // Specifies the modem speaker volume. 

mdmSpeakerVolumeWhisper, // Lowest volume level. 

mdmSpeakerVolumeLow, // Low/reasonable volume level. 

mdmSpeakerVolumeMedium, // Normal /average volume level (Default) . 

mdmSpeakerVolumeHigh // Highest volume level. 
}; 

NOTE: Not all modems are capable of adjusting modem speaker volume. 

msgModemSetCommandState 

Sets the modem into command mode. 

Takes nothing, returns STATUS. Category: modem service request. 

#define msgModemSetCommandState MakeMsg(clsModem, 33) 

msgModemSetDuplex 

Sets the duplex mode for inter-modem communications while on-line. 

Takes MODEM_DUPLEX_MODE, returns STATUS. Category: modem service request. 

tdefine msgModemSetDuplex MakeMsg(clsModem, 34) 

Enum32 (MODEM_DUPLEX_MODE) { // Indicates data transmission line duplex. 

mdmDuplexHalf, // Data transmitted in one direction at a 

// time ( the line must be turned around) . 
mdmDuplexFull // Data can be transmitted in both 

// directions simultaneously (Default) . 
}; 

NOTE: Not all modems are capable of setting the duplex once on-line. 

msgModemSetMNPMode 

Sets the MNP mode of operation. 

Takes MODEM_MNP_MODE, returns STATUS. Category: modem service request. 

tdefine msgModemSetMNPMode MakeMsg(clsModem, 35) 
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Enum32 (MODEM_MNP_MODE) { // MNP mode in which modem is to operate. 

mdmMNPModeDirect, // Disable MNP mode (default) . 

mdmMNPModeReliable, // Both modems must support MNP levels 

// 1-4 (5 if enabled) before a connection 

// can be made. 

mdmMNPModeAutoReliable, // Attempt to establish an MNP connection; if 

// it fails establish a direct connection. 

mdmMNPModeLAPM // LAPM connection. 
}; 

NOTE: Not all modems provide MNP support. 



msgModemSetMNPCompression 

Sets MNP class 5 compression on or ofF. 

Takes MODEM_MNP_COMPRESSION, returns STATUS. Category: modem service request. 

♦define msgModemSetMNPCompression Ma]ceMsg(clsModem, 36) 

ArgyRients Enum32 (MODEM_MNP_COMPRESSION) { // Type of compression to use in MNP mode. 

mdmMNPCompressionOff , // Disable MNP level 5 compression (default) . 

mdmMNPCompressionOn // Enable MNP level 5 compression. 
}; 



msgModemSetMNPBreakType 

Specify how a break is handled in MNP mode. 

Takes MODEM_MNP_BREAK_TYPE, returns STATUS. Category: modem service request. 

♦define msgModemSetMNPBreakType MakeMsg(clsModem, 37) 

Enum32 (MODEM_MNP_BREAK_TYPE) { // How breaks are handled in MNP mode. 

mdmMNPSendNoBreak, // Do not send break to remote modem. 

mdmMNPEmptyBuffersThenBreak,// Empty data buffers before sending break. 

mdmMNPImmediatelySendBreak, // Send break when received (default) . 

mdmMNPSendBreaklnSequence // Send break relative to data to be sent. 
}; 



msgModemSetMNPFlowControl 

Specify the flow^ control to use in MNP mode. 

Takes MODEM_MNP_FLOW_CONTROL, returns STATUS. Category: modem service request. 

♦define msgModemSetMNPFlowControl MakeMsg(clsModem, 38) 

Enum32 (MODEM_MNP_FLOW_CONTROL) {// Indicates the flow control for MNP mode. 

mdmMNPFlowControlDisable, // No flow control used (default) . 

mdmMNPFlowControlXonXoff, // Use Xon/Xoff flow control. 

mdmMNPFlowControlHardware // Use RTS/CTS flow control. 
}; 
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msgSvcGetMetrics 

Passes back the current modem metrics. 

Takes P_SVC_GET_SET_METRICS, returns STATUS. Category: superclass message. 

imenfs typedef struct MODEM_METRICS { 

MODEM_D IAL_MODE mdmDialMode ; 

MODEM_DUPLEX_MODE mdiiiDuplexMode; 

MODEM_SPEAKER_CONTROL mdmSpeakerCont rol ; 

MODEM_SPEAKER_VOLUME mdmSpeakerVolume ; 

MODEM_TONE_DETECTION indmToneDetection; >; 

MODEM_ANSWER_MODE mdmAnswerMode; > 

MODEM AUTO ANSWER mdmAutoAnswer; u 

QJ 

U32 mdmAutoAnswerRings ; Z 

MODEM_MNP_MODE mdmMNPMode ; § 

MODEM_MNP_COMPRESSION mditiMNPCompression; ^ 

MODEM_MNP_BREAK_TYPE mdmMNPBreakType ; 

MODEM_MNP_FLOW_CONTROL mdinMNPFlowCont rol ; 
} MODEM_METRICS, *P_MODEM_METRICS ; 

meiits The pMetrics field of SVC_GET_SET_METRICS is expected to point to a buffer capable of receiving 

MODEM_METRICS as described below. 

msgSvcSetMetrics 

Sets current modem metrics, and re-initializes the modem with specified metrics. 

Takes P_SVC_GET_SET_METRICS, returns STATUS. Category: superclass message. 

meiifs The pMetrics field of SVC_GET_SET_METRICS is expected to point to a buffer containing 

MODEM_METRICS as described above. 

msgSvcCharactersticsRequested 

Passes back the characteristics of the modem service. 

Takes P_SVC_CHARACTERISTICS, returns STATUS. Category: superclass message. 

#define mdmHWManufactureNameLength 15 
#define mdmHWModelNameLength 15 

iftienfs typedef struct { // Modem hardware manufacturer. 

CHAR name[mdmHWManufactureNameLength+l] ; // Name of manufacturer. 
} MODEM_HARDWARE_MANUFACTURER, *P_MODEM_HARDWARE_MANUFACTURER; 

typedef struct { // Model of modem hardware. 

CHAR name[mdmHWModelNameLength+l] ;// Name of model. 
} MODEM_HARDWARE_MODEL, *P_MODEM_HARDWARE_MODEL; 

Enum32 {MODEM_HARDWARE_FEATURES) { // Modem hardware capabilities. 
mdmHWCapAutoDial = flagO, // Auto dialing. 
mdmHWCapAutoAnswer = flagl, // Auto answer. 
mdmHWCapAutoBaudDetect = flag2, // Auto baud detection. 
mdmHWCapCallTypeDiscrimination = flagS, // Call type discrimination 

// (Fax, Data, Voice) . 
mdmHWCapPhoneJackConnectOetect = flag4, // Phone jack connect and 

// disconnect event reporting. 
mdmHWCapRingSignalMachineWakeUp= flag5 // Ring signal detection 

// wakes up dormant machines. 
}; 
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typedef struct { // Size of internal modem I/O buffers. 

S32 sizelnputBuffer; // Input buffer size. 

S32 sizeOutputBuffer; // Output buffer size. 

} MODEM_HARDWARE_BUFFERS, *P_MODEM_HARDWARE_BUFFERS ; 

Enum32 (MODEM_DCE_CONTROL) { // Firmware DCE protocol/command sets. 

mdmDCEControlAT = flagO // Hayes 'AT' commands. 

}; 
typedef struct MODEM_CHARACTERISTICS { // Modem hw & sw characteristics. 

MODEM_HARDWARE_MANUFACTURER hardwareManufacturer; 

MODEM_HARDWARE_MODEL hardwareModel; 

MODEM_HARDWARE_FEATURES hardwareFeature; 

MODEM_HARDWARE_BUFFERS hardwareBuf fer; 

MODEM_DCE_CONTROL dceControl; 

MODEM_SIGNALLING_MODES signallingMode ; 

MODEM_LINK_CONTROL linkControl; 

U32 spare [4]; 

} MODEM_CHARACTERISTICS, *P_MODEM_CHARACTERISTICS; 

The pBuf field of SVC_CHARACTERISTICS is expected to point to a bufifer capable of receiving 
MODEM_CHARACTERISTICS as described below. 

Implementors of clsModem services that wish to provide capabilities not described within 
MODEM_CHARACTERISTICS should contact GO Corporation to ensure such clsModem enhancements 
are standardized and noted within MODEM_CHARACTERISTICS. Thank you. 



Class Messages 



msgNew 

Creates a new instance of a modem service. 

Takes P_MODEM_NEW, returns STATUS. Category: class message. 

tdefine modemNewFields serviceNewFields 

typedef struct MODEM_NEW 
{ 

modemNewFields 
} MODEM_NEW, *P_MODEM_NEW; 

Error Return Values: percolated up from other classes, 

msgNewDefaults 

Initializes the MODEM_NEW structure to default values. 

Takes P_MODEM_NEW, returns STATUS. Category: class message. 



ftie 



a typedef struct MODEM_NEW 

giirneiits { 

modemNewFields 
} MODEM NEW, *P MODEM NEW; 



Sets: 



pArgs->svc . style . autoOption 

pArgs->svc. style. exclusiveOpen = true; 

pArgs->svc. style. waitForTarget = false; 

pArgs->svc.pManagerList = pManagerList; 

pArgs->svc.numManagers = sizeof (pManagerList )/sizeof (OBJECT) ; 

static OBJECT pManagerList [] = 

{ 

theModems // clsModem is one of theModems. 
}; 



u 
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cIsModem error status values 

This modem service doesn't (or cannot) support the current request due to hardware or firmware 
constraints. 

#define stsModeinNot Supported MakeStatus (clsModem, 1) 

A request to the modem service contained a parameter that is invaUd. 

tdefine stsModemBadParameter MakeStatus (clsModem, 2) 

The size of the buffer suppHed to get/set modem service metrics or characteristics is incorrect. 

tdefine stsModemBufferSizeError MakeStatus (clsModem, 3) 

The modem service was unable to find and/or open its target service. 

tdefine stsModemTargetError MakeStatus (clsModem, 4) > 

SJ 

The modem service is not open. The current request requires that it be open. 2 

z 
tdefine stsModemNotOpen MakeStatus (clsModem, 5) O 

The modem has responded to a modem command with an error response. 

tdefine stsModemErrorResponse MakeStatus (clsModem, 6) 

The modem has responded to a modem command with a response that was unrecognized. 

tdefine stsModemUnrecognizedResponse MakeStatus (clsModem, 7) 

The modem responded with a notification of carrier loss after dialing, attempting to go online, or being 

online. 

tdefine stsModemNoCarrier MakeStatus (clsModem, 8) 

The modem didn't detect a dial tone while dialing to establish a connection. 

tdefine stsModemNoDialTone MakeStatus (clsModem, 9) 

The modem didn't detect an answer tone after dialing to establish a connection. 

tdefine stsModemNoAnswer MakeStatus (clsModem, 10) 

The modem has been unable to successfully transmit a data frame to the remote node. 

tdefine stsModemTransmitError MakeStatus (clsModem, 11) 

The modem has been unable to successfully receive a data frame to the remote node. 

tdefine stsModemReceiveError MakeStatus (clsModem, 12) 

The modem has detected a cyclic redundancy check error within a data frame received from the remote 
node. 

tdefine stsModemCRCError MakeStatus (clsModem, 13) 

The modem has detected a busy signal after dialing a telephone number. 

tdefine stsModemLineBusy MakeStatus (clsModem, 14) 

The modem service could not locate a window within one of its option cards. This is an internal error. 

tdefine stsModemNoSuchWindow MakeStatus (clsModem, 255) 

clsModem non-error status values 

None currently defined 
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OBXSVC.H 



This file contains the API definition for clsOBXService. 
clsOBXService inherits firom clsIOBXService. 

Provides default behavior for Outbox Services. 

tifndef OBXSVC_INCLUDED 
tdefine OBXSVC_INCLUDED 

tifndef IOBXSVC_INCLUDED 
tinclude <iobxsvc.h> 
#endif 

1. Introduction 

In PenPoint, output operations are handled by a special class of services known as the "outbox services." 
An outbox service implements the "deferred output" feature in PenPoint: This concept permits a user to 
specify output operations regardless of the readiness of output devices. If the output device (e.g., a 
printer, a phone plug, a LAN connection, etc.) is not available or not connected, documents waiting for 
output will be placed into an "output queue" associated with the output service. (This output queue is a 
special section in the system Outbox notebook.) Thus, the actual output process is deferred until the 
output device becomes ready. 

The Target of an Outbox Service 

PenPoint expects that the PenPoint computer will not always be attached to most output devices. 
Therefore, the output process for any PenPoint documents will be deferred until a connection is 
established. The software controlling an input/output device is often implemented as an I/O service. In 
most cases, an outbox service will make such an I/O service as its "target." (See service.h for more 
information about target services in general.) Examples of I/O services include drivers for serial ports, 
parallel ports, data and/or fax modems, and LAN servers. By making an I/O service its target, an outbox 
service is notified whenever the physical output device becomes connected or disconnected. When an 
outbox service is not actively sending out a document, the connection status of the device is displayed in 
the "Status" column of the Outbox notebook Table of Contents. 



Enabling and Disabling an Outbox Service 

An outbox service must be "enabled" before its output process can begin. This enabled state is 
represented by a checkbox in the "Enabled?" column of the Outbox notebook TOG. Typically, an 
output device permits only exclusive access. If multiple outbox services are connected to the same output 
device, only one can be enabled at a time. Enabling an outbox service causes it to become the "owner" of 
its target service. The service remains "enabled" until either it is manually disabled by the user (i.e., by 
unchecking the "Enabled?" box); or until it willingly releases ownership of the device so that another 
service can become the new owner. For more details on the notion of service ownership, see the service 
API in service.h. 
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The concept of enabling or disabling an outbox service also provides a convenient mechanism for the 
user to manage an output device that can not automatically determine whether or not it becomes 
connected or disconnected. Because the outbox service will not be informed when its target service is 
connected or disconnected, its status will always remain "Connected" regardless of the connection status 
of the physical device. Such services can be explicitly disabled to prevent documents from being sent to a 
device that is not ready for output. 

Managing the Output Process via the Outbox 
Service Protocol 

Each instance of an outbox service has a corresponding section in the system Outbox notebook. The 
name of the service and the name of the section are the same. For example, the user may create two 
instances of an outbox service class named "DotMatrix," say "Engineering Printer" and "Upstairs." 
Each instance will have its own output queue, implemented as a section called "Engineering Printer" 
and "Upstairs" in the outbox notebook. The primary function of an outbox service is to manage the 
output queue for each service instance. This function is implemented by a standard outbox protocol 
consisting of 8 inter-related messages, as summarized below: 

The client of an outbox service first sends insgOBXSvcMovelnDoc or msgOBXSvcCopylnDoc to the 
outbox service instance, telling it to add an existing PenPoint document to its output queue. Once a 
document is added to the outbox, msgOBXSvcPollDocuments informs an outbox service that it should 
check to see if conditions are right to start an output process. Other events may also cause the outbox 
service to receive msgOBXSvcPollDocument. For example, an outbox service will self-send this message 
when the service has just been enabled. If the service is enabled and the output device is connected, the 
service sends msgOBXSvcNextDocument to self to locate the next document ready for output. If a 
document exists in the output queue but is not ready for output, the service self-sends 
msgOBXSvcScheduIeDocument to reschedule output at a later time. If a document is ready for output, 
the service will lock the document with msgOBXSvcLockDocument, and kick off the output process 
with msgOBXSvcOutputStart. At the end of the output process, the document being sent will send 
msgOBXDocOutputDone to the outbox service. Finally, if the output finished normally, the service 
self-sends msgOBXSvcPollDocuments again to see if anything else is ready for output. If the output 
didn't finish normally, the service self-sends msgOBXSvcUnlockDocument to restore the document to 
its "pre-output" state. 

Outbox Documents 

The primary focus of an outbox service is to manage its output queue. An output queue is essentially a 
collection of documents located in an outbox section. The primary focus of an outbox document is to 
manage a single output job. 

An outbox document can be any PenPoint document, i.e., an instance of an application inheriting from 
clsApp. It can be created, opened, and closed just like a regular page in the notebook. An example of an 
outbox document would be an "address envelope" for an electronic mail service. 

An outbox document is also responsible for interacting with the outbox service and controlling the 
output process, such as sending out an electronic mail message through a communication link. Thus, in 
addition to responding to cIsApp messages, an outbox document also understand the following 
clsOBXService messages: 

msgOBXDocOutputStartOK 

For details see the description for each message. 
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Writing Your Ovs^n Outbox Service 

clsOBXService is an abstract class. You should always create a subclass of it. This is because 
clsOBXService only manages the output queue, it does not actually cause the output to happen. 
Typical^, your outbox service will inherit the output queue management behavior from clsOBXService, 
and add any service-specific behaviors for the communication protocol or devices you need to handle. 

The default behavior of the outbox service does not support sophisticated scheduling algorithms that 
may be required by some services. However, it is not difficult to replace some default behaviors with new 
ones. The messages you may want to handle on your own include: 

msgOBXSvcMovelnDoc 

For example, the default behavior of msgOBXSvcNextDocument treats the output queue as a simple, 
Fist-In-First-Out queue. If this is not sufficient for the service you wish to develop, you can provide your 



Another example would be msgOBXSvcLockDocument and msgOBXSvcUnlockDocument. Their 
default behavior is to mark the document so that gestures over the document icon will not be recognized 
while output is in progress. A msgOBXSvcUnlockDocument typically indicates that the output has 
been aborted for some reason. You may wish to add to the default behavior, such as notifying your 
observers that some error has just occurred. 

For details see the description for each message. 

Working with Existing Outbox Services 

As explained before, all output operations should be performed through an outbox service in order to 
take advantage of the "deferred output" feature of PenPoint. An application or a service can "bypass" the 
standard outbox protocol only if the output device is always present or is rarely detached from the 
PenPoint computer. 

The key to working with an existing outbox service is to conceptually break up the output process into 
two distinct phases. The first phase is either adding an existing PenPoint document to the output queue, 
or creating a special document of some sort in temporary storage and and then move it into the output 
queue. The second phase is the actual output process, during which a device-specific data stream is sent 
out via some communication link. clsOBXService provides a framework for managing the transition 
from one phase to another. 

The separation of these two phases of output operation has an additional benefit. In many cases, an 
application developer can avoid writing a new outbox service in order to handle application-specific 
output ftinctions. It is often sufficient to handle only one of the two phases of the output operaton. 
There are several options, as explained below: 

One inexpensive solution is to have the application export the data into a format that is easier to output 
under an existing outbox service. For example, a database document can generate a report as an ASCII 
file or a word processor document and move it into a printer, fax or e-mail outbox section. Similarly, a 
spreadsheet document can export its pie chart into a popular drawing program document and move it to 
the outbox for output. 

Another approach is to allow the database or spreadsheet document itself to be moved or copied into the 
output queue. When the document receives msgOBXSvcOutputStart, it knows that the output device 
is ready. It then proceeds to perform the output operation the old-fashioned way. This alternative may 
be an attractive one if we wish to port an existing PC application to PenPoint. Such applications already 



own behavior and pass back a document not on the top of the queue, or even a document not located in z 

the Outbox notebook if it makes sense for the service. P 



u 
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have sophisticated output capabihties, and we only need to ensure not to start the output process until 
the device is ready. The obvious disadvantage of this approach is that it requires additional memory if we 
have to make a copy of the document in order to put it into the outbox. 

A third approach represents a compromise between the two. During the first phase of the output 
operation, a "surrogate" document, rather than the real one, is copied into the output queue. This 
surrogate document not only understands the outbox output protocol, but also knows how to 
communicate with the original document. It is effectively a "pointer" back to the original document. 
When the output process begins, the surrogate document communicates with the original one to cause 
the device-specific data stream to be sent to the correct output port. 

Services that Handle Input and/or Output 

clsOBXService deals only with output operations. For those services that want to handle input 
operations, a similar class clsINBXService is provided by PenPoint. If a service (e.g., an electronic mail 
service) wants to handle both input and output, another abstract class, cIsIOBXService, is provided. 
clsIOBXService associates the service with both an input queue and an output queue. (The input queue 
is a section in the system Inbox notebook.) The service, the inbox section, and the outbox section all 
have the same name. In fact, clsOBXService is implemented as a subclass (hence a subset) of 
clsIOBXService. 



Class Messages 



msgNewDefaults 

Initializes the P_OBXSVC_NEW structure to default values. 
Takes P_OBXSVC_NEW, returns STATUS. Category: class message. 

typedef struct OBXSVC_NEW_ONLY { 

OBJECT sectionClass; // class of the outbox section (for output queue) 

// This must be clsNBToc or a subclass of it. 

U32 unusedl; 

U32 unused2; 

U32 unusedS; 

} OBXSVC_NEW_ONLY, *P_OBXSVC_NEW_ONLY; 

#define obxServiceNewFields \ 
ioSvcNewFields \ 

OBXSVC_NEW_ONLY obxsvc; 

typedef struct OBXSVC_NEW { 

ObxServiceNewFields 
} OBXSVC_NEW, *P_OBXSVC_NEW; 

Zeroes out pArgs->obxsvc and sets...>iobxsvc.out.autoPoll = true;>obxsvc.sectionClass 

clsNBToc; 

msgNew 

Creates a new outbox service object. 

Takes P_OBXSVC_NEW, returns STATUS. Category: class message. 

typedef struct OBXSVC_NEW { 

ObxServiceNewFields 
} OBXSVC NEW, *P OBXSVC NEW; 
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msgOBXSvcSwitchlcon 

Toggles the outbox icon (to empty or filled) if neccessary. 

Takes nothing, returns STATUS. Category: class message. 

tdefine msgOEXSvcSwitchlcon msglOBXSvcSwitchlcon 

Comments Check the content of the outbox notebook. Show the "filled" icon if any document is found. Show the 

"emtpy" icon otherwise. 

msgOBXDocGetService 

Gets the service name. y. 

Takes P_OBX_DOC_GET_SERVICE, returns STATUS. Category: class message. p 

111 

tdefine msgOBXDocGetService msglOBXDocGetService Z 

O 

l.rgumerifs typedef Struct OBX_DOC_GET_SERVICE { u 

OBJECT document; // In: document uid 

CHAR svcName [nameBuf Length] ; // Out: service name 
} OBX_DOC_GET_SERVICE, *P_OBX_DOC_GET_SERVICE; 

mments Get the name of the service associated with an outbox document. If the document has not been placed 

into an outbox section, stsFailed is returned. 

Note that the document must be at the top level of an outbox section. That is, if the document is 
embedded within another document which is in an outbox section, stsFailed will be returned because 
the document is not at the top level of an outbox section. 

msgOBXDocInOutbox 

Checks if a document is in a section in the Outbox. 

Takes P_OBX_DOC_IN_OUTBOX, returns STATUS. Category: class message. 

tdefine msgOBXDocInOutbox msglOBXDocInlOBox 

gortienfs typedef struct OBX_DOC_IN_OUTBOX { 

UUID uuid; // In: document uuid 

CLASS svcClass; // In: service class to check for 
} OBX_DOC_IN_OUTBOX, *P_OBX_DOC_IN_OUTBOX; 

mm&nfs This message can be sent to clsOBXService to check if a PenPoint document represented by 

pArgs->uuid is already in the output queue of an outbox service inheriting from pArgs->svcClass. stsOK 
is returned if it is, stsFailed otherwise. If pArgs->svcClass is objNull, stsOK is returned if the document 
is anywhere in the Outbox notebook. 



Messages Sent to an Outbox Service 
Instance 

msgOBXSvcMovelnDoc 

Moves a document into the outbox section. 

Takes P_OBXSVC_MOVE_COPY_DOC, returns STATUS. 

#define msgOBXSvcMovelnDoc msglOBXSvcMovelnDoc 
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typedef struct 0BXSVC_MOVE_COPY_DOC { 

FS_LOCATOR source; // In: Location of source document. 

Ul6 sequence; // In: Sequence number to move/copy in 

// front of. 

} OBXSVC_MOVE_COPY_DOC, *P_OBXSVC_MOVE_COPY_DOC; 

Superclass behavior is to move the document located at pArgs->source into the output queue associated 
with the outbox service. For example, set pArgs->sequence to 1 to move the document to the top of the 
queue. Set it to maxU16 to move the document to the bottom of the queue. 

After the document is moved (or copied) to the output queue, it is considered to be in a state ready for 
output, even though the service may not be connected at the time. Client should not alter the document 
in any way once it has been moved to the output queue. 

Subclasses can provide their own behavior if they wish. Remember to use the class message 
msgOBXSvcSwitchlcon to change the outbox icon. 

msgOBXSvcCopylnDoc 

Copies a document into the Outbox section. 

Takes P_OBXSVC_MOVE_COPY_DOC, returns STATUS. 

#define msgOBXSvcCopylnDoc msglOBXSvcCopylnDoc 

typedef struct OBXSVC_MOVE_COPY_DOC { 

FS_LOCATOR source; // In: Location of source document. 

Ul6 sequence; // In: Sequence number to move/copy in 

// front of. 

} OBXSVC_MOVE_COPY_DOC, *P_OBXSVC_MOVE_COPY_DOC; 

Same as msgOBXSvcMovelnDoc, except that the document is copied to the output queue. 

msgOBXSvcGetTempDir 

Passes back a handle for a temporary directory. 

Takes P_OBJECT, returns STATUS. 

#define msgOBXSvcGetTempDir msglOBXSvcGetTempDir 

This message is provided for clients who may want ot prepare their output document before moving it 
into the output queue. The handle of an "official" temporary directory is passed back and it can be used 
as temporary storage for documents, data, etc. Clients are responsible for deleting temporary files when 
they are done. The directory will be flushed after a warm boot. 

msgOBXSvcPollDocuments 

Polls all documents in an output queue and output those who are ready. 

Takes nothing, returns STATUS. 

#define msgOBXSvcPollDocuments msglOBXSvcPollDocuments 

This message tells the outbox service to look through its output queue and send out the first document 
ready for output. The service will first make sure that it is enabled and is connected to the designated 
output port. If these conditions are met, it will then self-send msgOBXSvcNextDocument to locate the 
next document ready for output. 

If msgOBXSvcNextDocument returns stsOK, indicating that a document is ready for output, this 
message proceeds to self-send msgOBXSvcLockDocument to lock the document, and finally 
msgOBXSvcOutputStart to initiate the output process. 
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If msgOBXSvcNextDocument returns stsOBXSvcDocReady, indicating that the section is not empty 
but none of the documents are ready for output, this message self-sends 
msgOBXSvcScheduleDocument to schedule the document passed back in pArgs at a later time. 

Subclasses normally do not process this message. 

msgOBXSvcNextDocument 



msgOBXSvcNextDocunieiit 

Passes back the next document ready for output. 

Takes P_OBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msgOBXSvcNextDocument msglOBXSvcNextDocument ^ 

typedef struct OBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc f 

OBJECT dir; // app dir of the doc O 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} OBXSVC_DOCUMENT, *P_OBXSVC_DOCUMENT ; 

Superclass behavior is to start from the top of the output queue and locate the first document ready for 
output. If one is found, information about the document is passed back in pArgs. The same pArgs will 
be passed to messages msgOBXSvcLockDocument and msgOBXSvcOutputStart. By default, a 
document is ready for output when it is closed. If the document is open, it will receive 
msgOBXDocOutputStartOK and it should return stsOK to indicate that it is ready for output. 

Subclasses can provide their own behavior if they wish. Return stsOBXSvcSectionEmpty to give the 
superclass an opportunity to change the outbox icon from filled to empty. 

StsOK A document is ready for output. 

StsOBXSvcSectionEmpty The output queue is empty. 

stsOBXSvcDocNotReady No document in the output queue is ready. 

Service- Specific Error Returns. 

msgOBXSvcPollDocuments 

msgOBXSvcLockDocument 

Locks the document in preparation for output. 

Takes P_OBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msgOBXSvcLockDocument msglOBXSvcLockDocument 

typedef struct OBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} OBXSVC_DOCUMENT, *P_OBXSVC_DOCUMENT ; 

This mess^e is a place holder for subclasses that may require additional preparatory work to be 
performed on a document before it is ready for output. For example, a document may have to be 
"locked" so that it can not be opened during the output process. This message may be used for other 
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purposes as well. For example, an outbox service may decide to store a light-weight "shadow" document 
(e.g., a report designator for a database application) in the output queue until it is chosen for output. 
The service then handles this message by converting the shadow document to a real one (e.g., the actual 
report). 

The superclass behavior for this message is to stamp the document directory with the filesystem attribute 
iobxsvcDocOutputlnProgress. This stamp will prevent any gestures over the document from being 
processed. This means that once a document is locked for output it can not be deleted, renamed, etc. via 
gestures. 

msgOBXSvcUnlockDocument 

msgOBXSvcUnlockDocument 

Unlocks a document that was previously locked. 

Takes P_OBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

#define msgOBXSvcUnlockDocument msglOBXSvcUnlockDocument 

typedef struct 0BXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length ] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} OBXSVC_DOCUMENT, *P_OBXSVC_DOCUMENT; 

This message is a place holder for subclasses that may require additional "cleanup" work to be 
performed on a document before it is put back to the output queue. 

The superclass behavior for this message is to remove the iobxsvcDocOutputlnProgress stamp on the 
document directory. 

msgOBXSvcLockDocument 

msgOBXSvcScheduleDocument 

Schedules a document that is not ready for output 

Takes P_OBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msgOBXSvcScheduleDocument msglOBXSvcScheduleDocument 

typedef struct OBXSVC_DOCUMENT { 

OBJECT uid; // uid of the doc 

OBJECT dir; // app dir of the doc 

OBJECT docClass; // class of the doc 

U16 sequence; // sequence of the doc 

CHAR pName [nameBuf Length ] ; // name of this doc 

P_UNKNOWN pDocData; // subclass' s private data 
} OBXSVC_DOCUMENT, *P_OBXSVC_DOCUMENT ; 

This message is sent when msgOBXSvcNextDocument locates a document in the output queue but the 
document is not ready for output. 

Subclasses should provide their own behavior. The default behavior is to release the ownership of the 
target service (i.e., become disabled), with the expectation that the user must manually schedule the 
document later on (by re-enabling the section.) 

msgOBXSvcNextDocument 



OBXSVC.H 445 

Messages Sent to an Outbox Service Instance 



OBJECT 


uid; 


OBJECT 


dir; 


OBJECT 


docClass; 


U16 


sequence; 


CHAR 


pName [nameBuf Length] 


P UNKNOWN 


pDocData; 



msgOBXSvcOutputStart 

Starts the output process for a document in the output queue. 

Takes P_OBXSVC_DOCUMENT, returns STATUS. Category: self-sent. 

tdefine msgOBXSvcOutputStart msglOBXSvcIOStart 

lessoge typedef struct OBXSVC_DOCUMENT { 

krgwmenfs OBJECT uid; // uid of the doc 

// app dir of the doc 

// class of the doc 

// sequence of the doc 

// name of this doc 

// subclass' 8 private data ^ 

} OBXSVC_DOCUMENT, *P_OBXSVC_DOCU]yiENT; t 

rtienf s Superclass behavior is to activate the outbox document if it isn't already active, and then send JJ| 

msgOBXDocOutputStart to the document instance. z 

O 

Subclasses can provide their ow^n behavior if they wish. 

msgOBXSvcOutputCancel 

Cancels the output process. 

Takes nothing, returns STATUS. 

tdefine msgOBXSvcOutputCancel msglOBXSvcIOCancel 

This message is sent to the service when the caller wishes to cancel any output operation in progress. 
The service responds to this message by sending msgOBXDocOutuptCancel to an active outbox 
document. After the document is cancelled, the service will post an error note to the user if there are 
other documents waiting to be processed. The user then decides whether or not the service should 
proceed to send the remaining documents. 

Subclasses do not normally process this message. 

msgOBXSvcOutputCleanUp 

Cleans up after the current output is done. 

Takes P_OBX_DOC_OUTPUT_DONE, returns STATUS. Category: self-post.. 

tdefine msgOBXSvcOutputCleanUp msglOBXSvcIOCleanUp 

Enum32 (OBX_DOC_EXIT_BEHAVIOR) { 

obxDocExitDoNothing = 0, 

obxDocExitDelete = 1, 

obxDocExitMarkAsFailed = 2, 

obxDocExitMarkAsCancelled = 3 
}; 

typedef struct OBX_DOC_OUTPUT_DONE { 

OBX_DOC_EXIT_BEHAVIOR behavior; // exit behavior 

P_UNKNOWN pDocData; // Unused: document specific data 

} OBX_DOC_OUTPUT_DONE, *P_OBX_DOC_OUTPUT_DONE; 

This message is posted to self as a result of the service receiving msgOBXDocOutputDone, which is 
sent by the outbox document when it finishes the output operation. The outbox document will be 
either deleted or marked as specified in pArgs, and when everything is properly cleaned up the service 
will post msgOBXSvcPollDocuments to self to see if anything else is waiting for output. 

Subclasses do not normally process this message. 

msgOBXDocOutputDone 
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msgOBXSvcStateChanged 

Tells observers that the service state just changed. 
Takes OBJECT, returns STATUS. Category: observer notification.. 
tdefine msgOBXSvcStateChanged msglOBXSvcStateChanged 

«tinieiits Informs observers that the state of a service has just changed. pArgs is the UID of the service. 

msgOBXSvcQueiyState 

Passes back the state of the service. 

Takes P_OBXSVC_QUERY_STATE, returns STATUS. 

#define msgOBXSvcQueryState , msglOBXSvcQueryState 

■giimenfs typedef struct { 

BOOLEAN enabled; // true if the service is enabled. 

CHAR status [nameBuf Length] ; // text describing the status of 

// the service. 
CHAR docName [nameBuf Length] ; // document being processed 

P_UNKNOWN pStateData; // subclass' s private data 

} OBXSVC_QUERY_STATE, *P_OBXSVC_QUERY_STATE; 

iriiments This message is typically used to query what state the service instance is in. 

msgOBXSvcGetEnabled 

Gets the enabled state of the service. 
Takes P_BOOLEAN, returns STATUS. 

#define msgOBXSvcGetEnabled msglOBXSvcGetEnabled 

^mnierits Subclasses can override this message and redefine the notion of "enabled." The default behavior of the 

superclass is to equate "enabled" with the ownership of the target service (i.e., output device). That is, 
the service is "enabled" when it owns the target service. By appending to or replacing the default 
behavior, a subclass can define additional conditions which must be met before a service is considered 
enabled. 

msgOBXSvcSetEnabled 

Sets the enabled state of the service. 

Takes BOOLEAN, returns STATUS. 

#define msgOBXSvcSetEnabled msglOBXSvcSetEnabled 

Mtiraents This message is sent to the service in response to service notification messages msgSvcOwnerAcquired 

and msgSvcOwnerReleased. Subclasses can provide their own behavior and thereby redefine the notion 
of "enabled" for the service. If they do, they must pass this message up to the ancestor so that observers 
of the outbox service will be properly notified. 



Outbox Document Messages 
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msgOBXDocOutputStartOK 

Asks the outbox document if it is OK to start the output process 

Takes nothing, returns STATUS. 

tdefine msgOBXDocOutputStartOK msglOBXDocIOStartOK 

When an outbox service finds an opened document in the outbox section, it sends this message to the 
document instance, asking whether it's OK to start the output operation while the document remains 
open. When the document receives this message, it should return stsOK to give the service permission 
to begin the output process. An error status, including stsNotUnderstood, is taken to mean that the 
document instance vetos the request and the service will not start the output process. 



z 
z 

msgOBXDocOutputStart 8 

Tells an outbox document to start the output process. 

Takes nothing, returns STATUS. 

#define msgOBXDocOutputStart msglOBXDocIOStart 

This message is sent by the outbox service to a document. The document should respond to this 
message by starting the output process. 

msgOBXDocOutputDone 

Tells the outbox service that output is finished. 

Takes P_OBX_DOC_OUTPUT_DONE, returns STATUS. Category: client responsibility. 

tdefine msgOBXDocOutputDone msglOBXDocIODone 

typedef struct OBX_DOC_OUTPUT_DONE { 

OBX_DOC_EXIT_BEHAVIOR behavior; // exit behavior 

P_UNKNOWN pDocData; // Unused: document specific data 

} OBX_DOC_OUTPUT_DONE, *P_OBX_DOC_OUTPUT_DONE ; 

When the output process is finished, the outbox document in charge of the output should send this 
message to the outbox service. This message must be sent even if the output process has been aborted. 
The pArgs for this message tells the outbox service what to do with the outbox document. If 
obxDocExitDelete is specified, the document will be removed from the outbox. In all other cases the 
document will be unlocked and left in the outbox. If either obxDocExitMarkAsCancelled or 
obxDocExitMarkAsFailed are specified, the name of the document will be altered to provide visual 
indication for the user that the output process has not completed successfully. 

msgOBXDocGetService 



msgOBXDocOutputCancel 

Tells an outbox document to cancel the output process. 

Takes nothing, returns STATUS. 

tdefine msgOBXDocOutputCancel msglOBXDocIOCancel 
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This message is used by the outbox service to inform a document that it should cancel the output 
process. The document should handle this message by terminating its output operation and then 
sending msgOBXDocOutputDone to the service with pArgs->behavior set to 
obxDocExistMarkAsCancelled. 



msgOBXDocStatusChanged 

Tells the outbox service that the document status is changed. 

Takes P_OBX_DOC_STATUS_CHANGED, returns STATUS. Category: client responsibility. 

tdefine msgOBXDocStatusGhanged msglOBXDocStatusChanged 

typedef struct OBX_DOC_STATUS_CHANGED { 

CHAR status [nameBuf Length] ; // Text describing document state 

P_UNKNOWN pDocData; // Unused: document-specific data 

} OBX_DOC_STATUS_CHANGED, *P_OBX_DOC_STATUS_CHANGED; 

This message is sent by the outbox document to the service whenever its status has just changed. This 
status is displayed on Status column for the outbox section, in the Outbox notebook. 
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OPENSERV.H 



This file contains the API definition for clsOpenServiceObject. 

clsOpenServiceObject inherits from clsStream. 

Provides defauh behavior for open service objects. 

All open service object classes must be a subclass of clsOpenServiceObject. This superclass forwards all 
clsService messages to the actual service instance. It also allows a subclass to easily get the service 
instance that it is associated with. 

tifndef OPENSERV_INCLUDED 
tdefine OPENSERV_INCLUDED 

tifndef STREAM_INCLUDED 
#include <stream.h> 
#endif 



Messages 



msgNew 

Creates a new service object. 

Takes P_OSO_NEW, returns STATUS. Category: class message. 



typedef struct OSO NEW ONLY { 



OBJECT 

U32 
U32 
U32 
U32 



servicelnstance; 

unusedl; 
unused2 ; 
unusedS; 
unused4 ; 



// This is filled in by 
// clsService at open time. 



} OSO_NEW_ONLY, *P_OSO_NEW_ONLY, OSO_METRICS, *P_OSO_METRICS; 

Idefine openServiceObjectNewFields \ 
streamNewFields \ 

OSO_NEW_ONLY openServiceObject; 

typedef struct OSO_NEW { 

OpenServiceObjectNewFields 

} OSO NEW, *P OSO NEW; 



msgOSOGetServicelnstance 

Returns the service instance that this object is associated with. 

Takes P_OBJECT, returns STATUS. 

#define msgOSOGetServicelnstance MakeMsg (clsOpenServiceObject, 1) 



^^ili^iii^ii-piilii^^ 




PPORT.H 



This file contains the API definition for clsParallelPort. 

clsParallelPort inherits firom clsMILService. 

This mil service provides the interface between the parallel printer mil device and the rest of Penpoint. 
This interface allows for the configuring of the parallel printer mil device and for printing using the 
parallel printer mil device. The pport mil service will typically only be accessed by printer drivers since 
they are responsible for rendering an image for printing. 

You access this mil service by using the standard service access techniques. These techniques are 
discribed in servmgr.h. 

The pport mil service is a member of the 'theParallelDevices' and 'thePrinterDevices' service managers. 

#ifndef PPORT_INCLUDED 
tdefine PPORT_INCLUDED 
tifndef GO_INCLUDED 
#include <go.h> 
#endif 

tifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

#endif 

#ifndef MIL_SERVICE_INCLUDED 

tinclude <milserv.h> 

tendif 



Common #clefines and typedefs 



typedef 

tdefine 
tdefine 
tdefine 
tdefine 
tdefine 

typedef 

{ 

U16 
U16 
U16 
U32 



OBJECT 



PPORT, *P PPORT; 



stsPPortBusy 
stsPPortOutOf Paper 
stsPPortOffLine 
stsPPortNoPrinter 
stsPPortPrinterErr 

struct PPORT METRICS 



version; 
devFlags; 
unitFlags; 
initDelay; 



MakeStatus (clsParallelPort, 1) 

MakeStatus (clsParallelPort, 2) 

MakeStatus (clsParallelPort, 3) 

MakeStatus (clsParallelPort, 4) 

MakeStatus (clsParallelPort, 5) 



// version number of pport 



//device flags (none defined) 
// unit flags (see dvparall.h) 
// time in microseconds init signal 
//is applied to printer 
// the printer should be ready to accept 
// another character within this time 
// period (in milliseconds) 
} PPORT METRICS, *P PPORT METRICS; 



U32 



interruptTimeOut ; 
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Parallel Port Class Messages 

msgPPortStatus 

returns the current hardware status of the printer. 
Takes P_PPORT_STATUS, returns STATUS. 

#define msgPPortStatus MakeMsg(clsParallelPort, 3) 

Idefine pportStsBusy flag7 // printer is busy 

tdefine pportStsAcknowledge flag6 // printer acknowledged char. 

#define pportStsEndOfPaper flagS // printer out of paper 

tdefine pportStsSelected flag4 // printer on line 

#define pportStsIOError flag3 // printer error occurred 

#define pportStsInterruptHappened flag2 // printer interrupt occurred 

iiiiie«fs typedef struct PPORT_STATUS 

{ 

U16 pport Status; 
} PPORT_STATUS, *P_PPORT_STATUS ; 

'pportStatus' is the contents of the parallel port status register. 

msgPPortStatus 

initializes the printer. 

Takes P_NULL, returns STATUS. 

tdefine msgPPort Initialize MakeMsg(clsParallelPort, 4) 

The printer is initialized by asserting the controflnitialize" to the printer for initDelay microseconds. 



msgPPortAutoLineFeedOn 

inserts a line feed after each carriage return. 

Takes P_NULL, returns STATUS. 

#define msgPPortAutoLineFeedOn MakeMsg(clsParallelPort, 5) 

The auto line feed signal to the printer is set active. 



msgPPortAutoLineFeedOff 

disables inserting a line feed after each carriage return. 

Takes P_NULL, returns STATUS. 

#define msgPPortAutoLineFeedOff MakeMsg(clsParallelPort, 6) 

The auto line feed signal to the printer is set inactive. 

msgPPortGetTimeDelays 

gets the initialization and interrupt time out intervals. 

Takes P_PPORT_TIME_DELAYS, returns STATUS. 

#define msgPPortGetTimeDelays MakeMsg(clsParallelPort, 7) 

typedef struct PPORT_TIME_DELAYS 

{ 

U32 initDelay; // initialization delay 

U32 interruptTimeOut; // interrupt time out 

} PPORT TIME DELAYS, *P PPORT TIME DELAYS; 
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Parallel Port Class Messages 

The initialization time period is the time the initiahzation pulseasserted to the printer in microseconds. 
The interrupt time outis the maximum time the printer will assert busy before beingto accept 
another character in milliseconds. 

msgPPortSetTimeDelays 

sets the initialization and interrupt time out intervals. 

Takes P_PPORT_TIME_DELAYS, returns STATUS. 

#define msgPPortSetTimeDelays MakeMsg(clsParallelPort, 8) 

Message typedef Struct PPORT_TIME_DELAYS 

Arguments { 

U32 initDelay; // initialization delay 

U32 interruptTimeOut; // interrupt time out 

} PPORT TIME DELAYS, *P PPORT TIME DELAYS; 



Z 

Neither value can be zero. It's best to get the presentbefore changing the time intervals. o 



u 



msgPPortCancelPrint 

cancels the printing of the buffer currently being printed. 

Takes P_NULL, returns STATUS. 

♦define msgPPortCancelPrint MakeMsg(clsParallelPort, 9) 

msgNew 

creates a new pport object. 

Takes P_PPORT_NEW, returns STATUS. 

#define pportNewFields \ 

milServiceNewFields 

ftrgyments typedef struct PPORT_NEW { 

pportNewFields 
} PPORT_NEW, *P_PPORT_NEW; 

STATUS EXPORTED ClsParallelPortlnit (void) ; 









SENDSERV.H 



This file contains the class definition and methods for clsSendableService. 

clsSendableService inherits from clsService. 

Provides the API for the services which appear on the Document Send menu. 

clsSendableService is an abstract superclass which defines the sendable services protocol. This protocol is 
used by the Send Manager and the address book to interact with services on theSendableServices service 
manager. All services on this list *must* implement this protocol. 

#ifndef SENDSERV_INCLUDED 
tdefine SENDSERV_INCLUDED 

tifndef ADDRBOOK_INCLUDED 
#include <addrbook . h> 
#endif 



Common #defines and typedefs 



Data window fields are empty. 
#define stsSendServAddrWinEmpty 



MakeWarning (clsSendableService, 1) 



Messages 



msgSendServCreateAddrWin 

Conveirts address data into a window displaying the data. 
Takes P_SEND_SERV_ADDR_WIN, returns STATUS. 



MakeMsg (clsSendableService, 1) 



#define msgSendServCreateAddrWin 

typedef struct SEND_SERV_ADDR_WIN { 

U16 numAttrs; 

P_ADDR_BOOK_ATTR att r s ; 

P_STRING addrSummary; 

BOOLEAN errNote; 

OBJECT win; 

} SEND_SERV_ADDR_WIN, *P_SEND_SERV_ADDR_WIN; 

This message is sent to a sendable service by the address book. A sendable service should create a display 
window(pArgs->win). The sendable service should wait for msgSendServFillAddrWin before it fills in 
the fields in the window. 

Parameters: 

pArgs->numAttrs In: number of attributes in the attrs array. 

pArgs->attrs In: an array of size pArgs->numAttrs. pArgs->attrs[x] .value contains what the sendable 
service needs to display. 

pArgs->win Out: sendable-service-created display window. 
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msgSendServGetAddrSummaiy 

given pArgs->attrs, set pArgs->addrSummary to be a displayable string that sums up the address. 

Takes P_SEND_SERV_ADDR_WIN, returns STATUS. 

fdefine msgSendServGetAddrSummary MakeMsg(clsSendableService, 9) 

Message typedef struct SEND_SERV_ADDR_WIN { 

Argomenfs U16 nuiiiAttrs; 

P_ADDR_BOOK_ATTR attrs; 

P_STRING addrSummary; 

BOOLEAN errNote; 

OBJECT win; 

} SEND_SERV_ADDR_WIN, *P_SEND_SERV_ADDR_WIN; 

Coftiments Parameters: 

pArgs->numAttrs In: number of attributes in the attrs array. 

pArgs->attrs In: an array of size pArgs->numAttrs. 

pArgs->addrSummary Out: a string that sums up the address information described in attribute-value 
form in pArgs->attrs. 

msgSendServFillAddrWin 

Sendable service refreshes pArgs->win with information in pArgs->attrs. 

Takes P_SEND_SERV_ADDR_WIN, returns STATUS. 

#define msgSendServFillAddrWin MakeMsg(clsSendableService, 8) 

Messsge typedef struct SEND_SERV_ADDR_WIN { 

Argymerifs U16 numAttrs; 

P_ADDR_BOOK_ATTR attrs; 

P_STRING addrSuiranary; 

BOOLEAN errNote; 

OBJECT win; 

} SEND_SERV_ADDR_WIN, *P_SEND_SERV_ADDR_WIN; 

Comments An address book sends a sendable service this message to refresh the window that contains information 

described in pArgs->attrs. 

Parameters: 

pArgs-> numAttrs In: number of attributes in the attrs arraj^. If 0, then clear all fields. 

pArgs->attrs In: an array of size pArgs->numAttrs. pArgs->attrs[x] .value contains what the sendable 
service needs to display. 

pArgs->win In: uid of sendable-service-created display window. 

msgSendServEncodeAddrWin 

Converts a window which displays address data into data. 

Takes P_SEND_SERV_ADDR_WIN, returns STATUS. 

#define msgSendServEncodeAddrWin MakeMsg{clsSendableService, 2) 

typedef struct SEND_SERV_ADDR_WIN { 

U16 numAttrs; 

P_ADDR_BOOK_ATTR attrs; 

P_STRING addrSummary; 

BOOLEAN errNote; 

OBJECT win; 

} SEND SERV ADDR WIN, *P SEND SERV ADDR WIN; 
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Messages 

The service must convert the window into an array of attribute-values, as described in 
ADDR_BOOK_SERVICE_DESC. Storage for this array should be created by the sendable service from a 
global heap. The caller client is responsible for freeing this storage. 

Parameters: 

pArgs->numAttrs Out: Number of elements in the .attrs array 

pArgs->attrs Out: fill in the values of each attribute. 

pArgs->errNote In: if TRUE, then the service should display some kind of note on the screen when 
error occurs during data collection and validation. 

pArgs->win In: the window to get the data from. Presumably the sendable service created this window 

in response to a previous msgSendServCreateAddrWin. t 

stsServiceDataWinEmpty All data element fields are empty. hJ 

z 
o 

u 



stsFailed Some error occurs during data collection and validation. O 



msgSendServEncodeAddrData 

Converts serrvice-specific data into ASCII byte array. 

Takes P_SEND_SERV_CONVERT_ADDR_DATA, returns STATUS. 

tdefine msgSendServEncodeAddrData MakeMsg{clsSendableService, 3) 

typedef struct SEND_SERV_CONVERT_ADDR_DATA { 

P_U8 pBuf; // In/Out: Encoded addressing data 

U16 bufLen; // In/Out: Length of pBuf 

U16 numAttrs; 

P_ADDR_BOOK_ATTR attrs; 

} SEND_SERV_CONVERT_ADDR_DATA, *P_SEND_SERV_CONVERT_ADDR_DATA; 

:or«ments *** This message is obsolete *** 

The service converts attributes in .attrs into ASCII. Storage for this array should be created by the 
service from osProcessSharedHeapId. The caller is responsible for freeing this storage. 

leturn ¥oiwe StsServiceDataWinEmpty All data element fields are empty. 

msgSendServDecodeAddrData 

Converts ASCII data into service-specific data. 

Takes P_SEND_SERV_CONVERT_ADDR_DATA, returns STATUS. 

tdefine msgSendServDecodeAddrData MakeMsg{clsSendableService, 4) 

typedef struct SEND_SERV_CONVERT_ADDR_DATA { 

P_U8 pBuf; // In/Out: Encoded addressing data 

U16 bufLen; // In/Out: Length of pBuf 

U16 numAttrs; 

P_ADDR_BOOK_ATTR attrs; 

} SEND_SERV_CONVERT_ADDR_DATA, *P_SEND_SERV_CONVERT_ADDR_DATA; 

*** This message is obsolete *** 

The resulting data is put into .attrs and update the attribute count in .numAttrs. 
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msgAppExecute 

Displays a UI for obtaining addressing info and executing the send. 

Takes P_APP_EXECUTE, returns STATUS. 

This message is a standard clsApp message which is forwarded to the service the user has selected from 
the standard "Send" menu. The service should create and display their UI for obtaining addressing 
information from the user. 

Declaration for the APP_EXECUTE data structure can be found in app.h 

msgSendServGetAddrDesc 

Responsibility of a sendable service to return its service attribute-value pairs that describe its service 
address 

Takes P_ADDR_BOOK_SVC_DESC, returns STATUS. 

Idefine msgSendServGetAddrDesc MakeMsg(clsSendableServiGe, 7) 

An address book usually send this message to a sendable service as part of of initialization to find out the 
service address description. 
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SERLINK.H 



This file contains the definition and methods for clsALAPSerial 

tifndef SERLINK_INCLUDED 
#define SERLINK_INCLUDED 

ALAP_SERIAL_NEW_ONLY , *P_ALAP_SERI AL_NEW_ONLY ; 
#define alapSerialNewFields \ 

serviceNewFields \ 

ALAP_SERIAL_NEW_ONLY alapSerial; 

ALAP_SERIAL_NEW, *P_ALAP_SERIAL_NEW; 
STATUS EXPORTED ClsSerLinklnit (void) ; 
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SIO.H 



This file contains the API for clsMILAsyncSIODevice. 

clsMILAsyncSIODevice inherits firom clsStream. 

Provides the serial port interface, see also stream.h for the stream messages. 



#ifndef SIO_INCLUDED 
tdefine SIO_INCLUDED 

♦include <go.h> 
#include <clsmgr.h> 
tinclude <milserv.h> 



Common #clefines and typedefs 



tdefine stsSioPortlnUse 
tdefine milDefaultBaudRate 
tdefine milDefaultXonChar 
tdefine railDefaultXoffChar 
tdefine milDefaultModemControl 
tdefine milDefaultStopBits 
tdefine milDefaultParityType 
tdefine milDefaultWordLength 
tdefine milDefaultXonTimeout 
tdefine milDefaultLineToStop 
typedef OBJECT SIO; 
typedef SIO * P_SIO; 
Enuml6(SI0_EVENT_MASK) { 

sioEventCTS = flagO, 

sioEventDSR = flagl, 

sioEventDCD = flag2, 

sioEventRI = flag3, 

sioEventRxChar = flag4, 



sioEventRxBreak = flag5, 
sioEventTxBufferEmpty = flag6, 
sioEventRxError = flag?, 
sioAllEvents = flagO | 

I flags 



1) 



MakeStatus (clsMILAsyncSIODevice, 

9600 
0x11 
0x13 

milDataTerminalReady | milRequestToSend 
milOneStopBit 
milNoParity 
milEightBitWord 
{U32) 30000 
milRequestToSend 



// CTS line has changed state 

// DSR line has changed state 

// DCD line has changed state 

// RI line has changed state 

// Rx buffer has become not empty. 

// Note: The receive buffer must be 

// empty for a received character 

// to generate this event! 

// Break condition has been received 

// Tx buffer has become empty 

// parity, framing, or overrun error 

flagl I flag2 | flag3 I flag4 

I flag6 I flagV 



}; 



Asynchronous SIO Class Messages 

msgSioBaudSet 



Comments 



Sets the serial port baud rate. 

Takes U32, returns STATUS. 

tdefine msgSioBaudSet MakeMsg (clsMILAsyncSIODevice, 4) 

Maximum possible setting 115200. Actual baud rate = (1 15200/((U32)(1 15200/baudRate))) Default 

setting 9600 baud 
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msgSioLineControlSet 

Sets serial port data bits per character, stop bits, and parity. 

Takes P_SIO_LINE_CONTROL_SET, returns STATUS. 

#define msgSioLineControlSet MakeMsg{clsMILAsyncSI0Device,5) 

Enuml6(SI0_DATA_BITS) { 

sioSixBits = 6, 

sioSevenBits = 7, 

sioEightBits = 8 
}; 
Enuml6(SI0_ST0P_BITS) { 

sioOneStopBit = 0, 

sioOneAndAHalfStopBits =1, 

sioTwoStopBits = 2 
}; 
Enuml6(SI0_PARITY) { 

sioNoParity =0, 

sioOddParity = 1, 

sioEvenParity = 2 
}; 
typedef struct { 

SIO_DATA_BITS dataBits; 

SIO_STOP_BITS stopBits; 

SIO_PARITY parity; 

} SIO_LINE_CONTROL_SET, *P_SIO_LINE_CONTROL_SET; 

Default setting 8 bits, 1 stop bit, no parity. 

msgSioControlOutSet 

Controls serial port output lines dtr and rts. 

Takes P_SIO_CONTROL_OUT_SET, returns STATUS. 

#define msgSioControlOutSet MakeMsg(clsMILAsyncSIODevice, 6) 

// true activates, false deactivates 

// true activates, false deactivates 

// true activates, false deactivates 

// true activates, false deactivates 
} SIO_CONTROL_0UT_SET, *P_SIO_CONTROL_OUT_SET; 

Default setting dtr active, rts active. 

msgSioControlInStatus 

Reads the current state of the serial port input control lines. 

Takes P_SIO_CONTROL_IN_STATUS, returns STATUS. 

fdefine msgSioControlInStatus MakeMsg(clsMILAsyncSI0Device,7) 

// out - true = active (Clear To Send) 

// out - true = active (Data Set Ready) 

// out - true = active (Data Carrier Detect) 

// out - true = active (Ring Indicator) 

} SIO_CONTROL_IN_STATUS, *P_SIO_CONTROL_IN_STATUS; 

tdefine rlsd dcd 



typedef struct { 




BOOLEAN 


dtr; 


BOOLEAN 


rts; 


BOOLEAN 


outl; 


BOOLEAN 


out 2; 



typedef struct { 




BOOLEAN 


cts; 


BOOLEAN 


dsr; 


BOOLEAN 


dcd; 


BOOLEAN 


ri; 
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msgSioFlowControlCharSet 

Defines serial port XON/XOFF flow control characters. 

Takes P_SIO_FLOW_CONTROL_CHAR_SET, returns STATUS. 

tdefine msgSioFlowControlCharSet MakeMsg(clsMILAsyncSIODevice, 8) 

typedef struct { 

U8 xonChar; // xon character (default control-Q) 

US xoffChar; // xoff character (default control-S) 

} SIO_FLOW_CONTROL_CHAR_SET, *P_SIO_FLOW_CONTROL_CHAR_SET; 

Valid only if xon-xoff flow control is enabled. 

Default xon character 0x1 1 (control-q), default xoff character 0x13 (control-s). ^ 



msgSioBreakSend 



z 
z 

Sends a break for the specified duration. w 

Takes P_SIO_BREAK_SEND, returns STATUS. 

tdefine msgSioBreakSend MakeMsg(clsMILAsyncSIODevice,ll) 

luments typedef struct { 

OS_MILLISECONDS milliseconds; // break duration 
} SIO_BREAK_SEND, *P_SIO_BREAK_SEND; 

iimerits Constant s transmitted on the serial line for the specified duration. Typical durations are around 

200-400 milliseconds). 

msgSioBreakStatus 

Sends back the number of breaks received so far. 

Takes P_SIO_BREAK_STATUS, returns STATUS. 

#define msgSioBreakStatus MakeMsg(clsMILAsyncSI0Device,13) 

|yiiieiits typedef struct { 

U32 breaksReceived; // out 

} SIO_BREAK_STATUS, *P_SIO_BREAK_STATUS; 

mnents Also clears the internal break counter. 

msgSioReceiveErrorsStatus 

Sends back the number of receive errors and the number of dropped bytes (due to buffer overflows). 

Takes P_SIO_RECEIVE_ERRORS_STATUS, returns STATUS. 

tdefine msgSioReceiveErrorsStatus MakeMsg(clsMILAsyncSIODevice, 36) 

lyments typedef struct { 

U32 droppedBytes; // out 

U32 receiveErrors; // out 

} SIO_RECEIVE_ERRORS_STATUS, *P_SIO_RECEIVE_ERRORS_STATUS; 

niTierifs Also clears the internal counters. 



464 PENPOINT API REFERENCE 

Part 10 / Connectivity 

msgSioInputBufferStatus 

Provides input buffer status. 

Takes P_SIO_INPUT_BUFFER_STATUS, returns STATUS. 

fdefine msgSioInputBufferStatus MakeMsg(clsMIIiAsyncSI0Device,16) 

Arguments typedef struct { 

U32 bufferChars; // out, number of chars in buffer 

S32 bufferRoom; // out, amount of empty room in buffer 

BOOLEAN receiverFrozen; // out, is receive frozen? 

} SIO_INPUT_BUFFER_STATUS, * P_SIO_INPUT_BUFFER_STATUS; 

Commeiits Sends back the number of characters in the input buffer and the amount of empty room in the input 

buffer. 

msgSioOutputBufferStatus 

Provides output buffer status. 

Takes P_SIO_OUTPUT_BUFFER_STATUS, returns STATUS. 

tdefine msgSioOutputBufferStatus MakeMsg(clsMILAsyncSI0Device,17) 

Arguments typedef struct { 

U32 bufferChars; // out, number of chars in buffer 

S32 bufferRoom; // out, amount of empty room in buffer 

BOOLEAN transmitterFrozen; // out, is transmit frozen? 

} SIO_OUTPUT_BUFFER_STATUS, * P_SIO_OUTPUT_BUFFER_STATUS; 

Comments Sends back the number of characters in the output buffer and the amount of empty room in the output 

buffer. 

msgSioInputBuflPerFlush 

Flushes the contents of the input buffer. 

Takes pNull, returns STATUS. 

tdefine msgSioInputBufferFlush MakeMsg(clsMILAsyncSI0Device,18) 

msgSioOutputBuflFerFlush 

Flushes the contents of the output buffer. 

Takes pNuU, returns STATUS. 

tdefine msgSioOutputBufferFlush MakeMsg(clsMILAsyncSIODevice, 19) 

msgSioFlowControlSet 

Selects flow control type. 

Takes P_SIO_FLOW_CONTROL_SET, returns STATUS. 

tdefine msgSioFlowControlSet MakeMsg(clsMILAsyncSIODevice,20) 
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rgyments Enuml6 (SIO_FLOW_TYPE) { 

sioNoFlowControl = 0x11, 

sioXonXoffFlowControl = 0x22, 

sioHardwareFlowControl = 0x44, 

//To independently set receive and transmit flow control OR together 

// one from each of the following two sets. 

// i.e., .flowControl = sioRxXonXoff | sioTxHardware; 

// YOU MUST SET BOTH THE TX AND RX FLOW CONTROL! 

// Transmit flow control 

sioTxNone = 0x01, 

sioTxXonXoff = 0x02, 

sioTxHardware = 0x04, 

// Receive flow control 

sioRxNone = 0x10, 

sioRxXonXoff = 0x20, ^ 

sioRxHardware = 0x40 > 

)■■ S 

typedef struct { ^ 

SIO_FLOW_TYPE flowControl; O 

} SIO_FLOW_CONTROL_SET, *P_SIO_FLOW_CONTROL_SET; 

sniHieiifs Flow control types: no flow control, XON/XOFF flow control, or hardware flow control. Default: 

XON/XOFF flow control. 

msgSioEventStatus 

Sends back current state of event word, and then clears the event word. 

Takes P_SIO_EVENT_STATUS, returns STATUS. 

tdefine msgSioEventStatus MakeMsg(clsMILAsyncSI0Device,21) 

typedef struct { 

SIO_EVENT_MASK eventMask; // out 

} SIO_EVENT_STATUS, *P_SIO_EVENT_STATUS; 

irnenfs Bit set indicates an event has occurred. Events do not have to be enabled for eventMask to be set. 



msgSioEventSet 

Enables event notification. 

Takes P_SIO_EVENT_SET, returns STATUS. 

tdefine msgSioEventSet MakeMsg{clsMILAsyncSIODevice,22) 

typedef struct { 

SIO_EVENT_MASK eventMask; // in, events to respond to 

OBJECT client; // object to inform when event happens 

} SIO_EVENT_SET, *P_SIO_EVENT_SET; 

Bits set in the eventMask enable msgSioEventHappened to be sent to uid. Default: eventMask = 0, all 
event notification disabled. 

msgSioEventGet 

Gets the current sio event setting. 

Takes P_SIO_EVENT_SET, returns STATUS. 

#define msgSioEventGet MakeMsg(clsMIIiAsyncSIODevice,29) 
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lesssge typedef struct { 

krgymenfs SIO_EVENT_MASK eventMask; // in, events to respond to 

OBJECT client; // object to inform when event happens 

} SIO_EVENT_SET, *P_SIO_EVENT_SET; 

msgSioEventHappened 

Notifies client of event occurance. 

Takes P_SIO_EVENT_HAPPENED, returns STATUS. 

tdefine msgSioEventHappened MakeMsg(clsMIIiAsyncSIODevice,23) 

ir§yr«eiifi typedef struct { 

SIO_EVENT_MASK eventMask; // out, bits set indicate event happened. 

OBJECT self; // object which generated message. 

} SIO_EVENT_HAPPENED, *P_SIO_EVENT_HAPPENED; 

otiiiiieftts Message sent to object to notify it of event occurrance. PossibJ^, more than one bit will be set in the 

event mask (bits may be set from disabled events, although disabled events never cause this message to 
be generated. Clears event mask. 

msgSioInit 

Initializes the serial device to its default state. 

Takes P_SIO_INIT, returns STATUS. 

#define msgSioInit MakeMsg{clsMIIiAsyncSIODevice,26) 

typedef struct { 

U32 inputSize; // size of the input buffer 

U32 outputSize; // size of the output buffer 

} SIO INIT, *P SIO INIT; 



msgSioGetMetrics 

Sends back the sio metrics. 

Takes P_SIO_METRICS, returns STATUS. 

#define msgSioGetMetrics MakeMsg(clsMILAsyncSIODevice,24) 

typedef struct { 

U32 baud; // out/in 

SIO_LINE_CONTROL_SET line; // out/in 

SIO_CONTROL_OUT_SET controlOut; // out /in 

SIO_FLOW_CONTROL_CHAR_SET flowChar; // out /in 

SIO_FLOW_CONTROL_SET flowType; // out /in 

// 

// Changing the bufferSize fields causes reinitialization of serial 

// chip! 

SIO_INIT bufferSize; // out/in 

U8 spare [12]; 

} SIO_METRICS, *P_SIO_METRICS; 

msgSioSetJMetrics 

Sets the sio metrics. 

Takes P_SIO_METRICS, returns STATUS. 

tdefine msgSioSetMetrics MakeMsg{clsMILAsyncSIODevice,25) 
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argyments 
Fynsfion Pn 



Comments 



typedef struct { 








U32 


baud; 


// 


out /in 


S IO_LINE_CONTROL_SET 


line; 


// 


out/in 


SIO_CONTROL OUT_SET 


controlOut; 


// 


out/in 


S IO_FLOW_CONTROL_CHAR_SET 


flowChar; 


// 


out /in 


S IO_FLOW_CONTROL_SET 


flowType; 


// 


out /in 



// 

// Changing the bufferSize fields causes reinitialization of serial 
// chip! 

SIO_INIT bufferSize; // out/in 

U8 spare [12]; 

} SIO_METRICS, *P_SIO_METRICS; 

msgSioSetReplaceCharProc 

Replaces the built in receive character interrupt routine. 

Takes P_SIO_REPLACE_CHAR, returns STATUS. 

tdefine msgSioSetReplaceCharProc MakeMsg(clsMILAsyncSIODevice, 72) 



U32 



handle) ; 



typedef struct SIO_REPLACE_CHAR 
{ 

P_SIO_CHAR_HANDLER pRxHandler; // address of character handler 

U32 handle; // user data (meaningless to 

// clsMILAsyncSIO) 
} SIO_REPLACE_CHAR, *P_SIO_REPLACE_CHAR; 

This message calls the user defined function when a character is received. The procedure has the option 
to filter the character or to return and have the character processed normally. The user defined fuction 
returns a BOOLEAN indicating whether the function filtered the character or not. 



msgNew 

Creates a new clsMILAsyncSIODevice object. 
Takes P_SIO_NEW, returns STATUS. 

kgyments typedef struct SIO_NEW 
{ 

milServiceNewFields 
} SIO_NEW, *P_SIO_NEW; 

' Asynchronous SIO Option Card Tags 



#define 


sioTagOptionCard 


MakeTag (clsMILAsyncSIODevice 


19) // 


Card tag 


tdefine 


sioTagName 


MakeTag (clsMILAsyncSIODevice 


20) 




tdefine 


sioTagBaud 


MakeTag (clsMILAsyncSIODevice 


21) 




tdefine 


sioTagFlowControl 


MakeTag (clsMILAsyncSIODevice 


22) 




tdefine 


sioTagParity 


MakeTag (clsMILAsyncSIODevice 


23) 




tdefine 


sioTagDataBits 


MakeTag (clsMILAsyncSIODevice 


24) 




tdefine 


sioTagStopBits 


MakeTag (clsMILAsyncSIODevice 


25) 




tdefine 


sioTagBaudSOO 


MakeTag (clsMILAsyncSIODevice 


40) 




tdefine 


sioTagBaud600 


MakeTag (clsMILAsyncSIODevice 


41) 




tdefine 


sioTagBaudl200 


MakeTag (clsMILAsyncSIODevice 


42) 




tdefine 


sioTagBaud2400 


MakeTag (clsMILAsyncSIODevice 


43) 




tdefine 


sioTagBaud4800 


MakeTag (clsMILAsyncSIODevice 


44) 




tdefine 


sioTagBaud9600 


MakeTag (clsMILAsyncSIODevice 


45) 




tdefine 


sioTagBaudl9200 


MakeTag (clsMILAsyncSIODevice 


46) 




tdefine 


sioTagBaud38400 


MakeTag (clsMILAsyncSIODevice 


47) 




tdefine 


sioTagBaud57600 


MakeTag (clsMILAsyncSIODevice 


48) 




tdefine 


sioTagBaudll5200 


MakeTag (clsMILAsyncSIODevice 


49) 
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tdefine sioTagFlowNone MakeTag 

fdefine sioTagFlowXonXoff MakeTag 

tdefine sioTagFlowHardware MakeTag 

tdefine sioTagParityNone MakeTag 

tdefine sioTagParityOdd MakeTag 

tdefine sioTagParityEven MakeTag 

tdefine sioTagBits? MakeTag 

tdefine sioTagBitsS MakeTag 

tdefine sioTagStopBitsOne MakeTag 

tdefine sioTagStopBitsTwo MakeTag 



(clsMILAsyncSIODevice, 55) 

(clsMILAsyncSIODevice, 56) 

(clsMILAsyncSIODevice, 57) 

(clsMILAsyncSIODevice, 60) 

(clsMILAsyncSIODevice, 61) 

(clsMILAsyncSIODevice, 62) 

(clsMILAsyncSIODevice, 65) 

(ClsMILAsyncSIODevice, 66) 

(clsMILAsyncSIODevice, 70) 

(clsMILAsyncSIODevice, 71) 



Function prototypes 



SK,rian Prototype STATUS EXPORTED ClsSioInit (void) ; 

void EXPORTED SioSemaClear (P UNKNOWN pHandle) ; 
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TP.H 



This file contains the class definition and methods for clsTransport. 

clsTransport inherits from clsOpenServiceObject. 

Provides the API for replaceable transport layer network protocols. 

#ifndef TP_INCLUDED 
tdefine TP_INCLUDED 

tifndef OPENSERV_INCLUDED 
#include <openserv.h> 
#endif 



Common typedefscodetypedef U8 TP_SERVICE; 



typedef U8 

typedef U8 

typedef U8 

typedef U8 

Service Types 



TP_QUEUE_SIZE; 
TP_ADDRESS, * P_TP_ADDRESS; 
TP_OPTIONS, * P_TP_OPTIONS; 
TP BUFFER, * P TP BUFFER; 



tdefine tpReliableService 1 
#define tpDatagramService 2 
tdefine tpTransactionService 3 

msgNew 

Creates a transport (socket) handle object. 

Takes P_TP_NEW, returns STATUS. 

typedef struct TP_NEW_ONLY { 

TP_SERVICE service; // service type 

} TP_NEW_ONLY, *P_TP_NEW_ONLY; 

typedef struct TP_NEW { 

OSO_NEW oso; 

TP_NEW_ONLY tp; 

} TP_NEW, * P_TP_NEW; 

msgDestroy 

Destroys a transport handle object. 
Takes OBJ_KEY, returns STATUS. 



msgTPAccept 

Accepts a connection request from a remote process. 

Takes P_TP_ACCEPT, returns STATUS. 

tdefine msgTPAccept MakeMsg( clsTransport, 1 ) 

typedef struct TP_ACCEPT { 

OBJECT newHandle; // Out: uid of transport handle 

P_TP_ADDRESS pAddress; // ptr to protocol dependent address 

} TP ACCEPT, *P TP ACCEPT; 
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msgTPBind 

Binds a transport handle to a transport address. 

Takes P_TP_BIND, returns STATUS. 

fdefine msgTPBind MakeMsg( clsTransport, 2 ) 

ArguiTienfs typedef struct TP_BIND { 

P_TP_ADDRESS pAddress; // ptr to protocol dependent address 
} TP_BIND, *P_TP_BIND; 

msgTPConnect 

Establishes a connection with a remote process. 

Takes P_TP_CONNECT, returns STATUS. 

#define msgTPConnect MakeMsg( clsTransport, 3 ) 

.(Irgwifisnfs typedef struct TP_CONNECT { 

P_TP_ADDRESS pAddress; // ptr to protocol dependent address 
} TP_CONNECT, *P_TP_CONNECT; 

msgTPListen 

Allocates space for a queue of incoming connection requests. 

Takes P_TP_LISTEN, returns STATUS. 

#define msgTPListen MakeMsgC clsTransport, 4 ) 

Argyitients typedef struct TP_LISTEN { 

TP_QUEUE_SIZE queueSize; // max number of connection requests 
} TP_LISTEN, *P_TP_LISTEN; 

msgTPRecv 

Receives a message. 

Takes P_TP_RECV, returns STATUS. 

#define msgTPRecv MakeMsg( clsTransport, 5 ) 

Argymsiifs typedef struct TP_RECV { 

P_TP_BUFFER pBuffer; // ptr to receive data buffer 

U16 length; // size of receive buffer in bytes 

U16 count; // number of bytes received 

P_TP_OPTIONS pOptions; // ptr to protocol dependent options 
} TP_RECV, *P_TP_RECV; 

msgTPRecvFrom 

Receives a datagram. 

Takes P_TP_RECVFROM, returns STATUS. 

#define msgTPRecvFrom MakeMsg( clsTransport, 6 ) 

Argiimersts typedef struct TP_RECVFROM { 

P_TP_BUFFER pBuffer; // ptr to receive data buffer 

U16 length; // size of receive buffer in bytes 

U16 count; // number of bytes received 

P_TP_ADDRESS pAddress; // ptr to protocol dependent address 

P_TP_OPTIONS pOptions; // ptr to protocol dependent options 
} TP RECVFROM, *P TP RECVFROM; 
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msgTPSend 

Sends a message. 

Takes P_TP_SEND, returns STATUS. 

#define msgTPSend MakeMsg( clsTransport, 7 ) 



typedef struct TP_SEND { 

P_TP_BUFFER pBuffer; 
U16 count; 

P_TP_OPTIONS pOptions; 

} TP SEND, *P TP SEND; 



// ptr to send data buffer 
// number of bytes to send 
// ptr to protocol dependent options 



msgTPSendTo 

Sends a datagram. 

Takes P_TP_SENDTO, returns STATUS. 

tdefine msgTPSendTo MakeMsg( clsTransport, 8 ) 



typedef struct TP SENDTO { 



P_TP_BUFFER 
U16 

P_TP_OPTIONS 
P TP ADDRESS 



pBuffer; 
count ; 
pOptions; 
pAddress; 



// ptr to send data buffer 

// number of bytes to send 

// ptr to protocol dependent options 

// ptr to protocol dependent address 



} TP SENDTO, *P TP SENDTO; 



msgTPSendRecvTo 

Sends a request and waits for a response. For transaction service only. 

Takes P_TP_SENDRECVTO, returns STATUS. 

tdefine msgTPSendRecvTo MakeMsg( clsTransport, 9 ) 



typedef struct TP_SENDRECVTO { 



P_TP_BUFFER 

U16 

P_TP_BUFFER 

U16 

U16 

P_TP_OPTIONS 

P TP ADDRESS 



pSendBuffer; 

sendCount ; 

pRecvBuffer; 

recvLength; 

recvCount ; 

pOptions; 

pAddress; 



// ptr to send data buffer 

// number of bytes to send 

// ptr to receive data buffer 

// size of receive buffer in bytes 

// number of bytes received 

// ptr to protocol dependent options 

// ptr to protocol dependent address 



} TP SENDRECVTO, *P TP SENDRECVTO; 



Status Codes 



tdefine 


stsTPnotSupported 


MakeStatus 


tdefine 


stsTPtooMany 


MakeStatus 


tdefine 


stsTPbadUser 


MakeStatus 


tdefine 


stsTPmaxUsers 


MakeStatus 


tdefine 


stsTPnoUser 


MakeStatus 


tdefine 


stsTPbadService 


MakeStatus 


tdefine 


stsTPnoSocket 


MakeStatus 


tdefine 


stsTPnoMemory 


MakeStatus 


tdefine 


stsTPlength 


MakeStatus 


tdefine 


stsTPnoTransaction 


MakeStatus 


tdefine 


stsTPddpLength 


MakeStatus 


tdefine 


stsTPnoBridge 


MakeStatus 


tdefine 


stsTPbadNetwork 


MakeStatus 


tdefine 


stsTPbadNode 


MakeStatus 


tdefine 


stsTPsocketlnUse 


MakeStatus 


tdefine 


stsTPpending 


MakeStatus 



(clsTransport,!) 
(clsTransport, 2) 
(clsTransport, 3) 
(clsTransport, 4) 
(clsTransport, 5) 
(clsTransport, 6) 
(clsTransport, 7) 
(clsTransport, 8) 
(clsTransport, 9) 
(clsTransport, 10) 
(clsTransport, 11) 
(clsTransport, 12) 
(clsTransport, 13) 
(clsTransport, 14) 
(clsTransport, 15) 
(clsTransport, 16) 
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#define 


stsTPddpQ 


MakeStatus 


tdefine 


stsTPoverflow 


MakeStatus 


tdefine 


stsTPbadParm 


MakeStatus 


tdefine 


stsTPfailed 


MakeStatus 


tdefine 


stsTPnameNotFound 


MakeStatus 


tdefine 


stsTPnamelnUse 


MakeStatus 


tdefine 


stsTPnewSocket 


MakeStatus 


tdefine 


stsTPnoRoom 


MakeStatus 


tdefine 


stsTPnoLink 


MakeStatus 



(clsTransport, 17) 
(clsTransport, 18) 
(clsTransport, 19) 
(clsTransport, 20) 
(clsTransport, 21) 
(clsTransport, 22) 
(clsTransport, 23) 
(clsTransport, 24) 
(clsTransport, 25) 
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Next up: 28 

This file contains the API definition for clsPreferences. 

clsPreferences inherits from clsObject. 

clsPreferences provides a shell to access system preferences. 

theSystemPreferences is a well-known instance of clsPreferences. theSystemPreferences provides access 
to read and write system wide preferences. 

clsPreferences supports a set of preferences. Preferences are stored as resources in the "current" system 
preferences resource file. An instance of clsPreferences, known as theSystemPreferences, is created at 
boot time. This should be the only instance of clsPreferences in the system. 

Preferences are named by well known resource id's (RES_ID's). This header file contains some predefined 
preference id's to simplify things. When defining new preferences, use the class that originated the 
preferences. 

Clients can get and set preferences by accessing the well known object theSystemPreferences. 

Preferences are stored in a resource file. Any request to read or write a preference will force a read or 
write to a file. This minimizes the amount of space required to store preferences. theSystemPreferences 
will respond to any resource file messaged defined in resfile.h and process them appropriate^. 

Remember, to read and write system preferences simply use the messages msgResReadData and 
msgResWriteData (or msgResUpdateData). theSystemPreferences forwards the msg to the current 
system preferences resource file. 

As an example of reading a system preference: 

U16 lineHeight; 
RES_READ_DATA read; 

read. res Id = prLineHeight; 

read. heap = 0; 

read.pData = &lineHeight; 

read. length = SizeOf (U16) ; 

Ob jectCall (msgResReadData, theSystemPreferences, Sread) ; 

An example of writing a system preference: 

U16 lineHeight; 
RES_WRITE_DATA write; 

write. resid = prLineHeight; 

write. pData = SlineHeight; 

write. length = SizeOf (U16); 

write. agent = resDefaultResAgent; 

ObjectCall (msgResWriteData, theSystemPreferences, &write) ; 

theSystemPreferences "knows" about certain preferences (listed in this file below) and performs 

whatever interaction is required to activate the new preference. It also handles certain system wide 

notification and actions when certain preferences change. For example, clsPreferences will cause the 

system to be re-drawn and re-fonted when the system preference for the font changes. 



476 PENPOINT API REFERENCE 

Part 11/ Resources 

clsPreferences will notify all observers when a preference has (potentially) changed. This will allow 
various objects to observe theSystemPrefereAces, and react to the preference changes. 

Whenever a number of preferences are being changed, clients may wish to send msgPrefsWritingMany, 
followed by the preference writes, and then msgPrefsWritingDone. clsPreferences will use these 
messages to delay any layout that may occur as a result of writing preferences that cause layout. 
clsPreferences will also send these messages to observers, allowing them to delay expensive operations 
until the preference changes are complete. As an example, when the preference set changes, 
msgPrefsWritingMany, followed by msgPrefsPreferenceChanged for each preference, followed by 
msgPrefsWritingDone is sent to the observers. 

clsPreferences supports the concept of different sets of preferences. A set of preferences is stored in a 
single resource file in a well-known preferences directory managed by thelnstalledPreferences. 
clsPreferences supports messages to change the current preference set to another one that is already filed. 
In addition, clsPreferences allows a preference set to start "clean". When PenPoint first starts up (or 
during a warm boot), theSystemPreferences will contain the set of preferences associated with the 
"current" preference set managed by thelnstalledPreferences. If no current set exists, 
theSystemPreferences will start with a "clean" preference set. When a preference set changes, 
clsPreferences will notify the observers of the changed preferences. This is because clsPreferences is 
notified via msglMCurrentChanged from the install manager (see instlmgr.h). 

To change the set of preference set programmatically, one must communicate with thelntallManager. 
An example code fragment to change a preference set. See instlmgr.h for details: 

IM_INSTALL install; 

install. locator. uid = theBootVolume; 

rn.fs. locator. pPath = "\\PenPoint\\prefs\\PREFERENCESET"; 

install. exist = imExistReactivate; 

install. listAttrLabel = 0; 

install. listHandle = 0; 

ObjectCall(msgIMInstall, thelnstalledPrefs, &install) ; 

ObjectCall(msgIMSetCurrent, thelnstalledPrefs, install. handle) ; 
tifndef PREFS_INCLUDED 
#define PREFS_INCLUDED 

tifndef CLSMGR_INCLUDED 
tinclude <clsmgr.h> 
#endif 

tifndef RESFILE_INCLUDED 
#include <resfile.h> 
#endif 

tifndef SYSGRAF_INCLUDED 

♦include <sysgraf.h> 

tendif 

#ifndef OS_INCLUDED 

tinclude <os.h> 

tendif 

Known Preferences in the System 

The following are the predefined resource names, the data that reading and writing will return, and 
some predefined return values for certain preferences. 

System Font 

prSystemFont is the resource id for the system font. Reads and writes of this id use a 
P_PREF_SYSTEM_FONT. This resource will affect the returned value from PrefsSysFontlnfo. 
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Changing this resource (via msgResWriteData) will cause the system to layout after notification of 
observers, which is expensive. This is done by doing an ObjectPost of msgPrefsLayoutSystem to self As 
a result, clsPreferences will compare this resource to the previous value to prevent layout and observer 
notification if the write did not change the value. 



tdefine tagPrSystemFont MakeWknResId (clsPreferences, 1) 

tdefine prSystemFont tagPrSystemFont 



Field Font 



prUserFont is the resource id for the field (user) font. Reads and writes of this id use a 
P_PREF_SYSTEM_FONT, This preference will affect the returned data from PrefsSysFontlnfo. 

Changing this resource (via msgResWriteData) will cause the system to layout after notification of 

observers, which is expensive. This is done by doing an ObjectPost of msgPrefsLayoutSystem to self As 

a result, clsPreferences will compare this resource to the previous value to prevent layout and observer 

notification if the write did not change the value. 

to 

#define tagPrUserFont MakeWknResId (clsPreferences, 2) S 

#define prUserFont tagPrUserFont d 

O 

This data structure is the what is read in and written when reading and writing when the resid is 
prSystemFont or prUserFont. It contains a font specification, and a font scale to use. 

typedef struct PREF_SYSTEM_FONT { 

SySDC_FONT_SPEC spec; // Font spec 

SCALE scale; // Scale: same for system and user font 

} PREF SYSTEM FONT, *P PREF SYSTEM FONT; 



Orientation 



Bell 



prOrientation is the resource id for the screen orientation. Reads and writes of this id use a a P_U8, 
whose values are defined below. 

Changing this resource (via msgResWriteData) will cause the system to layout after notification of 
observers, which is expensive. This is done by doing an ObjectPost of msgPrefsLayoutSystem to self As 
a result, clsPreferences will compare this resource to the previous value to prevent layout and observer 
notification if the write did not change the value. 

#define tagPrOrientation MakeWknResId (clsPreferences, 3) 

tdefine prOrientation tagPrOrientation 

tdefine prPortrait // Portrait mode 

tdefine prLandscape 1 // Landscape mode 

tdefine prPortraitReversed 2 // Portrait mode (rotated 180 degrees) 

tdefine prLandscapeReversed 3 // Landscape mode (rotated 180 degrees) 



prBeii is the resource id for ringing the warning bell. It reads and writes a P_U8, whose values are defined 
below. prBell is 

tdefine tagPrBell MakeWknResId (clsPreferences, 5) 

tdefine prBell tagPrBell 

tdefine prBellOn // Ring the bell 

tdefine prBellOff 1 // Don't ring the bell 
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Writing Style 



prWritingStyle is the resource id for the handwriting preference style. Reads and writes of this id use a 
P_U8, whose values are defined below. 

tdefine tagPrWritingStyle MakeWknResId(clsPreferences, 6) 

#define tagPrPrintingStyle MakeWknResId(clsPreferences, 6) 

tdefine prWritingStyle tagPrWritingStyle 

#define prPrintingStyle tagPrPrintingStyle // old name 

#define prMixedCase // Mixed case writer 

fdefine prCapsOnly 1 // All caps writer 



Date Format 



prDateFormat is the resource id for the desired date format. Reads and writes use a P_U8, whose values 
are defined below. This preference will affect the format of the string returned from PrefsDateToString. 

fdefine tagPrDateFormat MakeWknResId(clsPreferences, 7) 

#define prDateFormat tagPrDateFormat 

♦define prDateMDYFull // January 15, 1990 

#define prDateMDYAbbre 1 // Jan. 15, 1990 

fdefine prDateMDYSlash 2 // 1/15/90 

fdefine prDateMDYHyphe 3 // 1-15-90 

fdefine prDateMDYDot 8 // 1.15.90 

fdefine prDateDMYFull 4 // 15 January 1990 

fdefine prDateDMYAbbre 5 // 15 Jan. 1990 

fdefine prDateDMYSlash 6 // 15/1/90 

fdefine prDateDMYHyphe 7 // 15-1-90 

fdefine prDateDMYDot 9 // 15.1.90 

Gesture Timeout 

prGestureTimeout is the resource id for the gesture timeout, and is measured in 1/100's of a second. 
Reads and writes of this id use a P_U16 whose meaning is 1/100's of a second. 

fdefine tagPrGestureTimeout MakeWknResId(clsPreferences, 9) 

fdefine prGestureTimeout tagPrGestureTimeout 

Line Height 

prLineHeight is the resource id for the ruled line writing line height in edit pads. Reads and writes of 
this id use a P_U16, whose meaning is 1/ 100th s of an inch. Changing this preference only affects newly 
created ruled pads. 

fdefine tagPrLineHeight MakeWknResId(clsPreferences, 10) 

fdefine prLineHeight tagPrLineHeight 

Auto Suspend 

tagPrAutoSuspend is the resource id for auto suspend timeout. Reads and writes of this id use a P_U16, 
whose units are minutes. If the value is 0, the machine will not be auto suspended. 

Machines that do not support auto suspend use the auto suspend preference for the auto shutdown 
timeout. 

fdefine tagPrAutoSuspend MakeWknResId(clsPreferences, 11) 
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Auto Shutdov^n 



tagPrAutoShutdown is the resource id for auto shutdown timeout. Reads and writes of this id use a 
P_U16, whose units are hundredths of hours. If the value is 0, the machine will not auto shutdown. 

Machines that do not support auto suspend use the auto suspend timeout prefrence for auto shutdown, 
♦define tagPrAutoShutdown MakeWknResId(clsPreferences, 28) 

Pov/er Management 

prPowerManagement is the resource id that indicates if PenPoint should attempt to limit the 
computer's power consumption by turning off inactive devices 

♦define tagPrPowerManagement MakeWlcnResId(clsPreferences, 27) 
♦define prPowerManagement tagPrPowerManagement 

♦define prPowerManagement Off // power management not attempted 

♦define prPowerManagementOn 1 // power management attempted 

Floating Allov^ed i 

prDocFloating is the resource id that indicates if documents can be floated. Reads and writes of this id £ 

use a P_U8, whose meaning is defined below. 

♦define tagPrDocFloating MakeWknResId(clsPreferences, 12) 
♦define prDocFloating tagPrDocFloating 

♦define prDocFloatingOff // document floating not allowed 

♦define prDocFloatingOn 1 // document floating allowed 

Zooming Allov^ed 

prDocZooming is the resource id that indicates if documents can be zoomed. Reads and writes of this id 
use a P_U8, whose meaning is defined below. 

♦define tagPrDocZooming MakeWknResId{clsPreferences, 13) 

♦define prDocZooming tagPrDocZooming 

♦define prDocZoomingOff // document zooming not allowed 

♦define prDocZoomingOn 1 // document zooming allowed 

Left/Right Handed 

prHandPreference is the resource id that indicates a left; handed or right handed user. Reads and writes 
of this id use a P_U8, whose meaning is defined below. 

Changing this resource (via msgResWriteData) will cause the system to layout after notification of 
observers, which is expensive. This is done by doing an ObjectPost of msgPrefsLayoutSystein to self. As 
a result, clsPreferences will compare this resource to the previous value to prevent layout and observer 
notification if the write did not change the value. 

♦define tagPrHandPreference MakeWknResId (clsPreferences, 14) 

♦define prHandPreference tagPrHandPreference 

♦define prLeftHanded // Left Handed writer 

♦define prRightHanded 1 // Right Handed writer 

Scroll Margins Style 

prScrollMargins is the resource id that indicates a "fiiU" vs. "light" scroll bars. Reads and writes of this 
id use a P_U8, whose meaning is defined below. 
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Changing this resource (via msgResWriteData) will cause the system to layout after notification of 
observers, which is expensive. This is done by doing an ObjectPost of msgPrefsLayoutSystem to self. As 
a result, clsPreferences will compare this resource to the previous value to prevent layout and observer 
notification if the write did not change the value. 

#define tagPrScrollMargins MakeWknResId (clsPreferences, 26) 

tdefine prScrollMargins tagPrScrollMargins 

tdefine prScrollMarginsFull 
#define prScrollMarginsLight 1 

Character Box Width 

prCharBoxWidth is the resource indicating the width of char boxes for boxed writing fields. Reads and 
writes of this id use a P_U8, whose meaning is the width of the box in points. This preference only 
affects newly created character boxes. 

tdefine tagPrCharBoxWidth MakeWknResId (clsPreferences, 15) 

#define prCharBoxWidth tagPrCharBoxWidth 

Character Box Height 

prCharBoxHeight is the resource id indicating the height of char boxes for boxed writing fields. Reads 
^ and writes of this id use a P_U8, whose meaning is the height of the char box in points. This preference 
only affects newly created character boxes. 

#define tagPrCharBoxHeight MakeWknResId (clsPreferences, 16) 

#define prCharBoxHeight tagPrCharBoxHeight 

Hand Writing Timeout 

prHWXTimeout is the resource id indicating the handwriting timeout. Reads and writes of this id use a 
P_U16 whose meaning is 1/100's of a second. 

tdefine tagPrHWXTimeout MakeWknResId (clsPreferences, 17) 

tdefine prHWXTimeout tagPrHWXTimeout 

Input Pad Style 

prInputPadStyle is the resource id indicating the preferred style of handwriting pads. Reads and writes 
of this id use a P_U8, whose meaning is defined below. 

tdefine tagPrlnputPadStyle MakeWknResId (clsPreferences, 18) 
tdefine prInputPadStyle tagPrlnputPadStyle 

tdefine prInputPadStyleBoxed // Pad styles are boxed 

tdefine prInputPadStyleRuled 1 // Pad styles are Ruled 

tdefine prInputPadStyleRuledAndBoxed 2 // Pad styles are boxed — >ruled 

tdefine prInputPadStyleSegmented // Obsolete 

Hold Timeout 

prPenHoldTimeout is the resource id for the press hold timeout. Reads and writes of this id use a P_U16 
whose meaning is 1/100's of a second. 

tdefine tagPrPenHoldTimeout MakeWknResId (clsPreferences, 19) 

tdefine prPenHoldTimeout tagPrPenHoldTimeout 
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Pen Cursor 



prPenCursor is the resource id for whether the cursor is off or on. Reads and writes of this id use a P_U8, 
whose meaning is defined below. 

tdefine tagPrPenCursor MakeWknResId(clsPreferences, 20) 

Idefine prPenCursor tagPrPenCursor 

tdefine prPenCursorOff // Pen cursor should be off 

#define prPenCursorOn 1 // Pen cursor should be on 

Time Format 

prTimeFormat is the resource id for the preferred time format (miUtary or civiHan). Reads and writes of 
this id use a P_U8, whose meaning is defined below. This preference will affect the returned string from 
PrefsTimeToString. 

#define tagPrTimeFormat MakeWknResId{clsPreferences, 21) 

tdefine prTimeFormat tagPrTimeFormat 

tdefine prTimel2Hour // Display 12 hour times 

tdefine prTime24Hour 1 // Display 24 hour times 

Display Seconds 

prTimeSeconds is the resource id indicating if seconds should be displayed or not. Reads and writes of 
this id use a P_U8, whose meaning is defined below. This preference will affect the returned string from 
PrefsTimeToString. 

tdefine tagPrTimeSeconds MakeWknResId(clsPreferences, 22) 

tdefine prTimeSeconds tagPrTimeSeconds 

tdefine prTimeSecondsDisplay // Display seconds in time 

tdefine prTimeSecondsOff 1 // Don't display seconds in time 

Time 

prTime is the resource id for the system time. Reads and writes of this ID use a P_PREF_TIME_INFO, 
containing the current time information. 

tdefine tagPrTime MakeWknResId(clsPreferences, 23) 

tdefine prTime tagPrTime 

typedef union PREF_TIME_MODE { 

OS_SET_TIME_MODE writeMode; // In: which attributes to set (for write only) 

} PREF_TIME_MODE; 

typedef struct PREF_TIME_INFO { 

PREF_TIME_MODE mode; // In: read or write mode 

OS_DATE_TIME dateTime; // In/Out: date and time information 

} PREF_TIME_INFO, *P_PREF_TIME_INFO; 

Primary Input 

prPrimarylnput is the resource id defining the primary input device. Reads and writes of this id use a 
P_U8, whose meaning is defined below. 

tdefine tagPrPrimary Input MakeWknResId(clsPreferences, 24) 

tdefine prPrimarylnput tagPrPrimary Input 

tdefine prPrimarylnputPen // Primary input is with the pen 

tdefine prPrimarylnputKbd 1 // Primary input is with a keyboard 
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Unrecognized Character 

prUnrecCharacter is the resource id used for tlie unrecognized character glyph. Reads and writes of this 
id use a P_U8, whose meaning is defined below. 

tdefine tagPrUnrecCharacter MakeW]cnResId(clsPreferences, 25) 

tdefine prUnrecCharacter tagPrUnrecCharacter 

tdefine prUnrecCharacterQuestion 
fdefine prUnrecCharacterUnder 1 



Messages 



msgNew 

Creates a new preferences object. 

Takes P_PREFS_NEW, returns STATUS. Category: class message. 

typedef struct PREFS_NEW_ONLY { 

P_CHAR pPrefSet; // Preference set name 

} PREFS_NEW_ONLY, *P_PREFS_NEW_ONLY; 

tdefine prefsNewFields \ 

objectNewFields \ 

PREFS_NEW_ONLY prefs; 

typedef struct PREFS_NEW { 

prefsNewFields 
} PREFS_NEW, *P_PREFS_NEW; 

This message should not be called by clients. Creates a preferences object. If pPrefSet is pNull, the list 
will start out empty. Otherwise, pPrefSet is expected to be an already installed file title in the preferences 
directory. 

msgPrefsPreferenceChanged 

Sent to observers when a preference has changed. 

Takes P_PREF_CHANGED, returns STATUS. Category: observer notification. 

tdefine msgPrefsPreferenceChanged MsgNoError(MakeMsg(clsPreferences, 1)) 

typedef struct PREF_CHANGED { 

OBJECT manager; // Sender of the notification (theSystemPreferences) 

RES_ID prefid; // res Id of preference that changed 

} PREF_CHMGED, *P_PREF_CHANGED; 

Sent to observers. Notifies observers that a given preference has changed. Notifies with the manager 
(usually theSystemPreferences, as there are no other pre-defined instances of clsPreferences), and the 
RES_ID of the preference that has changed. 



msgPrefsLayoutSystem 

Causes the system to re-layout and re-paint. 

Takes NULL, returns STATUS. 

tdefine msgPrefsLayoutSystem MakeMsg (clsPreferences, 5) 

Causes the entire system to layout. If msgPreJ&WritingMany has not been called, posted to self when 
clsPreferences receives msgResWriteData and a new value has been written for prSystemFont, 
prUserFont, prOrientation, prHandPreference, or prScroIlMargins. If msgPrefsWritingMany has been 
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called, the layout will occur when msgPrefsWritingDone is called. Will be sent to observers when 
immediately before a layout of the system occurs due to a preference change. 

msgPrefsWritingMany 



msgPrefsWritingMany 

Indicates several preferences are to be written in succession. 

Takes NULL, returns STATUS. 

tdefine msgPrefsWritingMany MakeMsg(clsPreferences, 6) 

Comments Causes clsPreferences to delay the self-posting of msgPrefsLayoutSystem until it receives 

msgPrefsWritingDone. Useful when writing several preference changes at once, and the client does not 
want the system laying out several times. If, after this message is received, a msgResWrite of 
prSystemFont, prUserFont, prOrientation, prHandPreference, or prScrollMargins is received, 
clsPreferences will self-post msgPrefsLayoutSystem when msgPrefeWritingDone is received. After 
msgPrefsWritingDone is received, any other msgResWrite of these preferences will cause an immediate 
layout unless this message is sent again. Will be sent to observers to allow them to be aware that several 
preferences are being written. 

s«e Also msgPrefsWritingDone 

msgPrefsWritingDone 

Indicates completion of writing several preferences. 

Takes NULL, returns STATUS. 

tdefine msgPrefsWritingDone MakeMsg (clsPreferences, 7) 

Comments Causes the System to layout if necessary by self-posting msgPrefsLayoutSystem. You should send this 

message in conjunction with msgPrefeWritingMany to indicate that writing of successive preferences is 
complete. If a msgResWrite of prSystemFont, prUserFont, prOrientation, prHandPreference, or 
prScrollMargins with a new value has been done, layout will occur at this time. Will be sent to observers 
to indicate that a series of preferences writes have been completed. 

See M&u msgPrefsWritingMany 



Public Functions 



PrefsSysFontlnfo 

Passes back the system and user font information. 

Returns void. 

rgyments typedef struct PREF_SYSTEM_FONT_INFO { 

U8 scale; 

U16 sysFontId; 

U16 userFontId; 

} PREF_SYSTEM_FONT_INFO, *P_PREF_SYSTEM_FONT_INFO; 

incflors Prototy|>e void EXPORTED PrefsSysFontlnfo { 

P_PREF_SYSTEM_FONT_INFO pFontlnfo) ; 



%ments This function can be used to read all font information stored in the preferences fde at one time. 

Equivalent functionality exists with msgResRead. This fixnction is provided for convenience. 
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PrefsDateToString 

Returns a pointer to the string containing a formatted date. 

Returns P_CHAR. 

tdefine prefsMaxDate 19 

P_CHAR EXPORTED PrefsDateToString ( 
P_OS_DATE_TIME pTime, 
P_CHAR pStr) ; 

This function will return a string containing the ASCII representation of the formatted date based on 
the current user-preference for date. Puts the date into the string passed in. The longest possible string is 
18 characters (19 including the terminating 0) given the CURRENT formats. If additional formats are 
added, this may increase. 



PrefsTimeToString 

Returns a pointer to the string containing a formatted time. 
Returns P_CHAR. 

#define prefsMaxTime 11 

P_CHAR EXPORTED PrefsTimeToString ( 
P_OS_DATE_TIME pTime, 
P_CHAR pStr) ; 

This fiinction will return a string containing the ASCII representation of the time based on the current 
user preferences for time. Puts the time into the string passed in, and returns the string pointer. The 
longest possible string is 10 characters (11 including the terminating 0) given the current time formats. 
If additional formats are added, this may increase. 
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RESCMPLR.H 



This file contains definitions for input to the resource compiler. 

The resource compiler is a program which runs under MS-DOS. In conjunction with your resource 
compiler input and the C compiler it will create a PenPoint resource file. 

NOTE: THIS IS A MSDOS INCLUDE FILE, DO NOT CHANGE IT TO BE PENPOINT 
COMPATIBLE. 

tifndef RESCMPLR_INCLUDED 
tdefine RESCMPLR_INCLUDED 
#ifndef RESFILE_INCLUDED 
#include <resfile.h> 
tendif 



Common #clef ines and typedefs 



Types 



Prototype for the client-supplied agent writing routine. If you wish to supply your own agent writing 
routine then write a routine of type P_AGENT_TYPE and supply the address to the routine in the field 
pAgentWriteProc of RCJNPUT. Your routine should write out (using fwrite to file) its representation of 
the data described by pResInput (and optionally also by pAgentData). 



FoRCtion Prototype 



typedef void (PASCAL 
P_UNKNOWN 
struct RC_INPUT 
P_UNKNOWN 
U32 
U32 

); 



_AGENT_WRITE) ( 
file, 

* pRes Input, 
pAgentData, 
sparel, 
spare2 



// DOS file handle 

// Data described below 

// Res Agent specific data 

// For future 

// For future 



The resource compiler uses the information supplied by RCJNPUT to create resources. Typically only 
the first four or five fields of RCJNPUT are used. At a minimum you should set resid, pData and 
dataLen. You do not need to set dataLen if you set agent to resStringResAgent or 
resStringArrayResAgent (the resource compiler will infer dataLen from pData). You should set agent if 
you do not want the default resource data agent. You should set minSysVersion if it has a non-zero 
value. You may set objectData to true in the rare case that an object resource is being created by the 
resource compiler. You should set pAgentWriteProc and optionally pAgentWriteData if you are 
providing your own routine to write the resource data to the resource file. 



typedef struct RC INPUT { 



RES_ID 


resId; 


P UNKNOWN 


pData; 


U16 


dataLen; 


UID 


agent ; 


U16 


minSysVersion; 


U16 


reserved; 


BOOLEAN 


objectData; 


P AGENT WRITE 


pAgentWr i t eP roc ; 


P_UNKNOWN 


pAgentWriteData; 



// the resource ID 

// points to data 

// length of data 

// usually resDefaultResAgent 

// min sys version for resource 

// usually false 

// pNull, unless supplying routine 

// usually pNull 



} RC INPUT, *P RC INPUT, **PP RC INPUT; 
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If you use resTaggedStringArrayResAgent as the agent for a resource. Then the data must be a hst of 
RC_TAGGED_STRINGs. This is converted into a linear string array and the filed using the 
resStringArrayResAgent agent. 

tdefine resTaggedStringArrayResAgent ( (UID)MakeTag(clsResFile, Oxf f ) ) 

typedef struct RC_TAGGED_STRING { 

TAG tag; 

P_STRING pString; 

} RC_TAGGED_STRING, *P_RC_TAGGED_STRING; 

Public variable 

reslnput is an exported variable that the resource compiler expects. Each element in the reslnput array is 
a pointer to a structure describing the next resource. The list must be terminated with a null pointer. 

extern P_RC_INPUT reslnput []; // Resource compiler input 

Example 

Here is example input for rescmplr (or re): 

// Resource ids 

#define resIdRfANumber MakeWknResId(clsExample, 1) 

tdefine resIdRfAString MakeWknResId{clsExainple, 2) 

tdefine resIdRfAStringArray MakeWknResId(clsExample, 3) 

tdefine resIdRfATaggedStringArray MakeWknResId(clsExample, 4) 

tdefine tagExampleErrorBogus MakeTag(clsExample, 0) 
tdefine tagExampleErrorWrong MakeTag(clsExample, 1) 
tdefine tagExampleErrorAgain MakeTag(clsExample, 2) 

// A number. 

static U16 aNumber = 1; 

//A string array. 

static P_CHAR errorTextData [] = { 

"This is bogus.", 

"You got it wrong.", 

"I think you need to try again.". 



}; 



pNull // Define end of string array. 



// A tagged string array. 

// This is equivalent to the above string array even thought the 

// elements are in a different order. 

static P_RC_TAGGED_STRING errorTextTaggedData [] = { 

tagExampleErrorWrong, "You got it wrong.", 
tagExampleErrorAgain, "I think you need to try again.", 
tagExampleErrorBogus, "This is bogus.", 

pNull 
}; 

// Res compiler input for aNumber. 
static RC_INPUT aNumberRes = { 

resIdRfANumber, 

SaNumber, 

sizeof (aNumber) 
}; 
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// Res compiler input for aString. 
static RC_INPUT aStringRes = { 

resIdRf AString, 

"Sample string", 

0, // Size inferred by res compiler. 

resStringResAgent 
}; 

// Res compiler input for aStringArray . 
static RC_INPUT aStringArrayRes = { 

resIdRf AStringArray, 

errorTextData, 

0, // Size inferred by res compiler. 

resStringArrayResAgent 
}; 

// Res compiler input for aTaggedStringArray . 
static RC_INPUT aTaggedStringArrayRes = { 

res IdRf ATaggedSt ringArray , 

errorTextTaggedData, 

0, // Size inferred by res compiler. 

resTaggedStringArrayResAgent * 

}; O 

// Input for resource compiler. 
P_RC_INPUT reslnput [] = { 

StaNumberRes, 

&aStringRes, 

&aSt ringArrayRes , 

SaTaggedSt ringArrayRes , 

pNull 
}; 



«A 









RESFILE.H 



This file contains the API definition for clsResFile. 

clsResFile inherits from clsFileHandle. 

Provides resource and object fifing support. 

theSystemResFile is a well Icnown instance of clsResFile. 

clsResList inherits from clsList. 

ResLists are lists of resource files that act like a single resource file for reading and searching (but not 
writing). 

theProcessResList is a process well known instance of clsResList. 

A resource file maintains a collection of 'resources' each identified by a 'resource ID'. A resource is filed 
data or a filed object. The types of data supported are: byte array, string, and array of strings. It is also 
possible to create an 'agent' that reads and writes other kinds of data. 

A resource ID is a 32 bit TAG used as a unique (per file) key to identify and select a desired resource. 



Overview 



Resource files are used in three general ways: filing & unfiling objects, reading theProcessResList for 
configuration and customization information, and application specific data storage. 

♦ The most common case of filing &; unfiling objects is a page turn, which needs to save the state of a 
running process on the disk, and restore the state of another process from the disk. This is done by 
(un)filing the application framework, which (if everything is set up correctly) (un)files directly or 
indirectly all the objects that make up the state of the process. 

Filling of an object is initiated with msgResWriteObject which ends up sending msgSave to the 
object. The save procedure uses msgStreamWrite (everything except objects) and msgResPutObject 
(objects) to write out its instance data. Unfiling of the object is initiated with msgResReadObject 
which sends msgRestore to the (newly created) object. The restore procedure uses msgStreamRead 
and msgResGetObject to read its instance data back in. 

♦ theProcessResList is used for several reasons: to allow text to be stored separately from the code, to 
store pre-built UI objects, to allow applications to override system provided items, to provide a 
central set of system wide preferences, etc. To do this it normally (inside an application) contains 
four resource files: DOC.RES (specific to the document), AIP.RES (specific to the application), current 
system preferences file, and PENPOINT.RES (system wide resource file). They are searched in the 
order listed above. There are some utility fiinctions to access theProcessResList, see RESUTIL.H for 
more information on them. 

♦ There are many other ways to use resource files, but they are application specific. If you think you 
have a use for resource files, it is worth checking out, but do be carefixl, resource files are designed 
and optimized for the first two uses, and do not work well for everything that it at first seems like 
they should. 
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Ho>v a Resource ID is put together 

The fields in a Resource ID: 

TagNum (which resource object) = 8 bits 

Flags (see below) = 2 bits 

Admin (as usual) = 20 or 1 9 bits 

Scope (as usual) =1 or 2 bits 

They are laid out this way: 



Name: 0|tagNum |F| Admin+Scope 
Size: 1| 8 |2| 20+1 or 19+2 



The flags are interpreted as follows: 

Weil-Known Resource ID 

1 Dynamic Resource ID 

2 Well-Known List Resource ID 

3 RESERVED 

The Well-Knowns used here are the same ones used in other tags. This gives us three possible scopes: 
global, process and local. Because resource files are not tied to a process context, there is no difference 
between the global and process Well-Knowns. System and service classes should only use there own well 
known. Applications can not only use the well knowns for there own classes, they can also use all local 
well known values. 

Well-Known Resource Ids (flag == 0) can be used to store any kind of resource. 

The Dynamic Resource IDs (flag ==1) are used by the resource file in msgResPutObject to file nested 
objects. It is also possible for other code to allocate them using msgResNextDynResId. They may be 
used to file any kind of resource. We get 29 bits worth of Dynamic Resource IDs by combining the 
tagNum, admin and scope fields. 

Well-IGiown List Resource IDs (flag ==2) must be used with list resources to allow the Indexed 
Resource IDs (see below) to work. The only list resource defined by GO is the string array, but it is 
possible to define others. The tagNum field is split into two fields for List Resource IDs. 

The fields in a List Resource ID: 

Group of lists = 6 bits 

List in group = 2 bits 

Flags (always set to 0x2) = 2 bits 

Admin (as usual) = 20 or 19 bits 

Scope (as usual) = 1 or 2 bits 

They are laid out this way: 



Name: 0| Grp |L|2| Admin+Scope 

Size: 1| 6 |2|2| 20+1 or 19+2 
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The Groups are allocated as follows: 

00 - IF AVAILABLE TO DEVELOPERS 

TK Table Lists 

Standard Message Lists 

Quick Help Lists 

3F RESERVED FOR GO 

What an Indexed Resource ID is 

Indexed Resource IDs are used to access list resources. They are NOT Resource IDs, Each must be 
converted into the List Resource ID of the desired list plus an index into the list to fetch the desired 
data. 

The fields in a Indexed Resource ID: 

TagNum (index into list) = 8 bits 

Flags (which list) = 2 bits S 

Admin (as usual) = 20 or 19 bits O 



Scope (as usual) = 1 or 2 bits 

They are laid out this way: 



Name: 0|tagNum |F| Admin+Scope 

Size: 1| 8 121 20+1 or 19+2 



You will note that this provides eight bits not provided by a List Resource ID (the index) and is missing 
eight bits needed by it (the jflags and group). 

The eight bits of index allow each list to contain up to 256 items. Actually they can have more, but only 
the first 256 can be accessed this way. Since there are four lists for each Weil-Known, it is possible to 
access up to 1 ,024 items per group per Well- Known, 

We provide the missing bits as follows. Since we always map to a List Resource ID we know that the 
flags will be set to 0x2. Which group to use is determined by which API it is used with. Thus, the 
passing the same Indexed Resource ID to both Quick help and a TK table will result in different data 
items being used. 

Warnings to those going off the beaten path. 

The description above gives the standard way of allocating resource IDs, While there is special support 
for using them this way, and some other parts of the system in fact require this usage, the resource file 
itself does not care. The only time it puts a special interpretation on a resource ID is for 
well-known-object resource IDs, They have the top (sign) bit set to one. These are automatically created 
by the resource file, and to avoid trouble, should never be created by anything else. 

Dynamic resource IDs are based off^of a 29-bit count, and gaps are not reused. Because of this it is 
possible to run out. While this will not happen in 'normal' use, it is possible for uses that seem 
reasonable. So if you use them for anything other than normal object filing, or are repeatedly filing 
objects, make sure you do not run into this. 
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When an object resource is deleted from a resource file, the other objects it filed are NOT deleted, and 
there is no easy way of finding them to delete them. Because of this, repeatedly filing objects will result 
in the file growing without bound unless you work very hard to prevent it. 

Opening multiple handles on the same resource file has some limitations. It is possible to have as many 
read-only handles as desired, as long as there are no writable handles. If there is a writable handle, no 
other handles may be opened. This is do to a limitation of the current implementation. It maintains 
index information into the file on a per handle basis. If writing was allowed with multiple handles open, 
these tables would become invalid resulting in fatal errors of many kinds. 

While it is possible to use a resource file as a kind of mini-database, it was not designed or optimized for 
such a use. So, don't be surprised if you find it is not up to the task you would like to use it for. 

ResFile Debugging Flags (Shared with Penpoint 
kernel & fs) 

ResFile flag is 'G', values are: 

1-80 = Used by PenPoint Kernel (see os.h) 
-800 = Used by File System (see fs.h) 

1000 = Turns on debugging info for reading and writing resources. 
= Turns on timing stats 

= Turns on debugging info for intercepted Stream & FS messages. 
= TBD 

#ifndef RESFILE_INCLUDED 
#define RESFILE_INCLUDED 

#ifndef UUID_INCLUDED 
#include <uuid.h> 
#endif 

#ifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

#endif 

#ifndef OSHEAP_INCLUDED 

#include <osheap.h> 

#endif 

#ifndef LIST_INCLUDED 

finclude <list.h> 

#endif 

#ifndef FS_INCLUDED 

tinclude <fs.h> 

#endif 

Commoii #clefines and typedefs 

These are used to define resource IDs, both well known (client-defined) and dynamic (See uuid.h for 
comparison). Note that the count used for the dynamic resource IDs is managed internal to the 
resource file, and no attempt should be made to create them elsewhere. 

tdefine resFlagsWkn 0x0 

Idefine resFlagsDyn 0x1 

#define resFlagsLists 0x2 

Idefine resFlagsSpare 0x3 

Idefine resFlagWknObj ( (RES_ID) 0x80000000) 
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#define MakeWknResId{wk:n, i) \ 

MakeTagWithFlags (wkn, i, resFlagsWkn) 
tdefine MakeDynRes Id (count) \ 

MakeTagWithFlags (({U32) (count) )»8, ( (count) &OxFF) , resFlagsDyn) 
tdefine MakeListResId(wkn,grp, 1st) \ 

MakeTagWithFlags (wkn, ((((U32) (grp) )«2) + ( (1st) &0x03) ) , resFlagsLists) 
tdefine MakeWknObjResId(obj) ( (RES_ID) (obj) | resFlagWknObj) 

Extract the pieces from resource IDs. 

♦define ResWknObjResId(resId) ( (OBJECT) ( (resid) & -resFlagWknObj) ) 

tdefine ResDynldCount (resid) (WKNValue(resId)«8 | Tag(resld)) 

tdefine ResListGroup (resid) (Tag (resid) » 2) 

tdefine ResListList (resid) (Tag (resid) & 0x3) 

Tests on resource IDs 

tdefine WknObjResId (resid) ((resid) & resFlagWknObj) 
tdefine WknResId (resid) \ 

(! WknObjResId (res Id) && TagFlags (resid) != resFlagsDyn) 
tdefine WknItemResId (resid) \ 

(! WknObjResId (resId) && TagFlags (resid) == resFlagsWkn) 
tdefine WknListResId (resid) \ ^ g 

(! WknObjResId (resid) && TagFlags (resid) == resFlagsLists) 
tdefine DynResId(resId) \ ^ 

(! WknObjResId (resid) && TagFlags (resid) == resFlagsDyn) 

Constants 

tdefine resNilResId Nil(RES_ID) 

OBOLETE Resource IDs do NOT use. 

tdefine residRfSystemVersion MakeWknResId(clsResFile, 1) 

tdefine residRfApplicationVersion MakeWknResId(clsResFile, 2) 

How to make a Indexed resource ID. 

tdefine MakeIndexedResId(wkn, list, index) \ 
MakeTagWithFlags (wkn, index, list) 

The group identifiers used to convert from Indexed resource IDs to normal resource IDs. Values from 
0x00 to 0x1 F are available for use by applications. Values from 0x20 to 0x3F are reserved to the system. 

tdefine resGrpTK 0x20 

tdefine resGrpStdMsg 0x21 
tdefine resGrpQhelp 0x22 

Predefined Resource Agents 

These are used by both the resource compiler to define data resources and by msgResWriteData to 
dynamically write a resource. 

// Don't use these definitions, use the derived values below 
tdefine resDefaultObjAgent 3 // Use resObjectResAgent 

tdefine resDefaultDataAgent 4 // Use resDataResAgent 

tdefine resStringAgent 5 // Use resStringResAgent 

tdefine resStringArrayAgent 6 // Use resStringArrayResAgent 

tdefine MakePrivateResAgent (x) \ 

( (UID) MakeTag (clsResFile, x) ) 
// These are the pre-defined resource types 
tdefine resDefaultResAgent objNull 

tdefine resObjectResAgent MakePrivateResAgent (resDefaultObjAgent) 
tdefine resDataResAgent MakePrivateResAgent (resDefaultDataAgent) 
tdefine resStringResAgent MakePrivateResAgent (resStringAgent) 
tdefine resStringArrayResAgent MakePrivateResAgent (resStringArrayAgent) 
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Status Codes 



Types 



tdefine stsResResourceNotFound MakeStatus{clsResFile, 1) 

#define stsResNotDataResource MakeStatus(clsResFile, 2) 

tdefine stsResNotObjectResource MakeStatus (clsResFile, 3) 

#define stsResBufferTooSmall MakeStatus (clsResFile, 4) 

tdefine stsResNotFullyRead MakeStatus (clsResFile, 5) 

tdefine stsResGetNotFromRestore MakeStatus (clsResFile, 6) 

tdefine stsResPutNotFromSave MakeStatus (clsResFile, 7) 
// removed unused MakeStatus (clsResFile, 8) 

tdefine stsResWriteObjDynamicClass MakeStatus (clsResFile, 9) 
// removed unused MakeStatus (clsResFile, 10) 

tdefine stsResCompactlnReadOrWrite MakeStatus (clsResFile, 11) 

tdefine stsResIncorrectFileType MakeStatus (clsResFile, 12) 

tdefine stsResFileCorrupt MakeStatus (clsResFile, 13) 

tdefine stsResResourceTooBig MakeStatus (clsResFile, 14) 

tdefine stsResOutOfDynResIds MakeStatus (clsResFile, 15) 



// Object types. 

typedef OBJECT RES_FILE, *P_RES_FILE; 

typedef OBJECT RES_LIST, *P_RES_LIST; 

NOTE: That RESJD is already defined in clsmgr.h because it is referenced by msgSave & msgRestore: 

typedef TAG RES_ID, *P_RES_ID; // Resource ID 

// Modes used in msgNew to control the creation of the resource file. 
Enuml6(RES_NEW_M0DE) { 

// Will the file handle be shared? Also guarantees concurrence 

resSharedResFile = flagO, 

// Remove "deleted" fields on close 

resCompactOnClose = flagl, 

// Compact file when ratio of deleted to non-deleted reaches compactRatio . 

resCompactAuto = flag2, 

// Check to see that system version is new enough for resources. 

resVerifyVersions = flag3, 

// Allow unsafe opens, internal use only. 

resUnsafeOpen = flag4, 

// Default - No Concurrence, compact on close, verify versions. 

resNewDefault = resCompactOnClose | resVerifyVersions 
}; 

// Duplicate object checking flag for reading objects. 
Enuml 6 (RES_READ_OB J_MODE ) { 

resReadObjectOnce =0, // Should object resource be read once? 

resReadObjectMany =1 // Should object resource be read many times? 
}; 

// Duplicate object checking flag for writing objects. 
Enuml6(RES_WRITE_0BJ_M0DE) { 

resWriteObjectOnce =0, // Should object resource be written once? 

resWriteObjectMany =1 // Should object resource be written many? 
}; 

// Mode used to control msgResEnumResources . 
Enuml 6 (RES_ENUM_MODE ) { 

resEnumAll =0, // Enumerate all resource entries? 

resEnumByResIdClass =1, // Enumerate by wkn resource ID admin field? 

resEnumByObjectClass = 2, // Enumerate by object resource's class? 

resEnumByObjectUID = 3, // Enumerate by object resource's uid? 

resEnumByAgent =4, // Enumerate by resource's agent? 

resEnumNext = flagl4, // Or in to enumerate the next item. 

resEnumDefault = resEnumAll // Default - all resources. 
}; 



u 
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// Internal flag used to enumerate across resource lists. 
#define resEnumNextFile 0x8000 

// Indexed resource IDs. 

typedef TAG IX_RES_ID, *P_IX_RES_ID; 

Class ResFile Messages 

msgNew 

Creates a resource file object. 

Takes P_RES_FILE_NEW, returns STATUS. Category: class message. 

typedef struct RES_FILE_NEW_ONLY { 

RE S_NEW_MODE mode ; 

U16 compactMinimum; 

U16 compactRatio; 

U32 sparel; 

U32 spare2; 

} RES_FILE_NEW_ONLY, *P_RES_FILE_NEW_ONLY; S 

tdefine resFileNewFields \ O 

fsNewFields \ 

RES_FILE_NEW_ONLY resFile; 

typedef struct RES_FILE_NEW { 

resFileNewFields 
} RES_FILE_NEW, *P_RES_FILE_NEW; 

stsIncompatibleVersion Filed data is incompatible with system. 

stsResIncorrectFileType File is not a resource file. 

stsResFileCorrupt Size or contents of the file are not valid. 

stsFSAccessDenied Incompatible with existing handles(*) 

(*) Note that there can be only one open handle to a writable resource file. The file mode is 
automatically set to enforce this. 

A resource file compacts itself at close time if the resCompactOnClose flag was set in 
pNew->resFile.mode. 

If the resCompactAuto flag is set in pArgs->res.mode then it compacts itself when a resource is written 
or deleted, if the number of records is greater than compactMinimum and the number of deleted 
records is greater than compactRatio percent of the records in the file. 

For example, a value of 10 for compactMinimum and 50 for compactRatio implies that compaction 
should happen whenever there are more than 10 resources in the resource file and 50% of them have 
been marked as deleted. 

msgNewDefaults 

Initializes the RES_FILE_NEW structure to default values. 

Takes P_RES_FILE_NEW, returns STATUS. Category: class message. 

typedef struct RES_FILE_NEW { 

resFileNewFields 
} RES_FILE_NEW, *P_RES_FILE_NEW; 

Zeroes out pArgs->resFile and sets.. ..mode = resNewDefault;. compactRatio = 33;.compactMinimum = 50; 
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msgResFindResource 

Finds a resource in a resource file or a resource list 
Takes P_RES_FIND, returns STATUS. 
tdefine msgResFindResource 



MakeMsg(clsResFile, 1) 



typedef struct RES_FIND { 

RES_ID resid; 

RES_FILE file; 

UID agent; 

U32 offset; 
U16 
U16 



// In: Resource to find 

// Out: File location of resource 

// Out: Agent of the resource 

// Out: Offset in file (Careful!) 

minSysVersion; // Out: Min sys vers for the resource 
reserved; 
} RES_FIND, *P_RES_FIND; 

*** This message is obsolete, you should use msgResGetlnfo instead. 

This message may be used to determine if a resource exists and to get information about that resource. 
You must use it before writing or deleting a resource if you do not know which resource file (out of a 
resource list) contains the resource (Resource lists only act upon non-destructive messages). 

stsBadParam resId is a nil resource ID. 

stsResResourceNotFound No resource with the given resId exists. 



msgResGetlnfo 






Gets information on a resource in a resource file or a resource list. 

Takes P_RES_INFO, returns STATUS. 

#define msgResGetlnfo MakeMsg(clsResFile, 17) 



// In: Resource to find 



// Out 
// Out 
// Out 
// Out 
// Out 
// Out 



File location of resource 

Agent of the resource 

Class of object (if is object) 

Offset in file (Careful!) 

Size in file (Careful!) 

Min sys vers for the resource 



typedef struct RES_INFO { 

RES_ID resId; 

RES_FILE file; 

UID agent ; 

UID objClass; 

U32 offset; 

U32 size; 

U16 minSysVersion; 

U16 reservedl; 

U32 reserved; 

} RES_INFO, *P_RES_INFO; 

This message may be used to determine if a resource exists and to get information about that resource. 
You must use it before writing or deleting a resource if you do not know which resource file (out of a 
resource list) contains the resource (Resource lists only act upon non-destructive messages). This is an 
improved version of msgResFindResource. It gives a more usefijl set of values for agent (as in exactly 
what is in the file), and it returns the size of the resource in the file. 

StsBadParam resId is a nil resource ID. 

StsResResourceNotFound No resource with the given resId exists. 



msgResReadData 



Reads resource data from a resource file or resource list. 

Takes P_RES_READ_DATA, returns STATUS. 

#define msgResReadData MakeMsg(clsResFile, 2) 
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typedef struct RES_READ_DATA { 

RES_ID resid; // 

OS_HEAP_ID heap; // Nil if pData is user supplied buf 

P_UNKNOWN pData; // I/O: In: user buffer, Out: res data 

U32 length; // I/O: In: user buf len, Out: res len 

P_UNKNOWN pAgentData; // Agent-specific data 

U32 sparel; 

} RES_READ_DATA, *P_RES_READ_DATA; 

This message requires a destination for the read data. There are two choices. You can specify a pointer 
and a length for the data passed back (heap = null, pData = ptr, length = xx) or you can specify a valid 
heap from which the resource file will allocate memory for the data (heap = heap ID, pData = doesn't 
matter, length = doesn't matter). Typically if the size of the data is already known and it is small and 
short lived, then the data is "allocated" on the stack. Otherwise, the data is allocated on behalf of a heap. 

Some resources require additional data to identify the actual data to be passed back. For example, a 
string arrays resource requires additional information (the index into the array) to find the string to pass 
back. You specify an index in pAgentData (pAgentData = (P_UNKNOWN) index). 

stsBadParam resId is a nil resource ID or reading a string from a string array resource and the index u 

specified in pAgentData is out of range. O 

stsResResourceNotFound No resource with the given resId exists. 

stsResNotDataResource The found resource was an object resource. 

stsResBufferTooSmall Supplied buffer isn't big enough to hold data. 

msgResWriteData To write data to resource file. 

msgResReadObject To read an object from a resource file. 

msgResWriteData 

Writes resource data to a file. 

Takes P_RES_WRITE_DATA, returns STATUS. 

tdefine msgResWriteData MakeMsg(clsResFile, 3) 

typedef struct RES_WRITE_DATA { 

RES_ID resId; // 

P_UNKNOWN pData; // Data to be written 

U32 length; // Optional if agent can compute size 

UID agent; // Not used by msgResUpdateData 

P_UNKNOWN pAgentData; // Agent-specific data 

U32 sparel; 

} RES_WRITE_DATA, *P_RES_WRITE_DATA; 

This message writes data to the resource file. If the resource already exists it is marked as deleted and the 
new data is written to the end of the file. 

StsBadParam resId is a nil resource ID. 

stsResResourceTooBig Tried to write resource bigger than resource file can handle (l6Meg). 

msgResReadData To read data from resource file. 

msgResUpdateData To re-write data in a resource file. 

msgResWriteObject To write an object to a resource file. 
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msgResUpdateData 

Updates existing data resource data. 

Takes P_RES_WRITE_DATA, returns STATUS. 

#define msgResUpdateData MakeMsg(clsResFile, 4) 

Mcissege typedef struct RES_WRITE_DATA { 

Argyiiieiifs RES_ID resid; // 

P_UNKNOWN pData; // Data to be written 

U32 length; // Optional if agent can compute size 

UID agent; // Not used by msgResUpdateData 

P_UNKNOWN pAgentData; // Agent-specific data 

U32 sparel; 
} RES_WRITE_DATA, *P_RES_WRITE_DATA; 

Csminents Use this message if you know that a resource already exists and is only being updated. The only 

advantage of this message over msgWriteData is that you don't have to specify the agent. 

teturn Voliie stsBadParam resId is a nil resource ID. 

stsResResourceNotFound No resource with the given resId exists. 

stsResNotDataResource The found resource was an object resource. 

stsResResourceTooBig Tried to write resource bigger than resource file can handle (l6Meg). 
See Also msgResReadData To read data from resource file. 

msgResWriteData To write data to a resource file. 

msgResReadObject 

Reads a resource object from a resource file or resource list. 

Takes P_RES_READ_OBJECT, returns STATUS. 

#define msgResReadObject MakeMsg(clsResFile, 5) 

Argimierits typedef Struct RES_READ_OBJECT { 

RES_READ_OBJ_MODE mode; // Duplicate checking mode 

RES_ID res Id; // 

OBJECT_NEW objectNew; // Object passed back in new.uid 

RES_SAVE_RESTORE_FLAGS sysFlags; // Only for msgResReadObjectWithFlags 
U16 appFlags; // Only for msgResReadObjectWithFlags 

U32 sparel; 

} RES_READ_OBJECT, *P_RES_READ_OBJECT; 

Comments An object must be initialized before it can be read. You must send msgNewDefault to clsObject. 

There are two modes that can be applied to reading an object resource, resReadObjectOnce and 
resReadObjectMany. 

Setting mode to resReadObjectOnce, passed back the object that is associated with the resource stored 
in the resource file (per open). This guarantees that all filed references to a given object refer to the same 
object. This is the mode to use if you are unfiling data in a msgRestore procedure. There are other uses 
of it, but they can be very tricky, so make sure you read all of the documentation and understand it 
thoroughly before you try to use this any place other than a msgSave procedure. 

Setting mode to resReadObjectMany, passes back a new copy of the object without regard as to whether 
the object has already been read in before or not. This guarantees that each reader gets his own unique 
instance of the object. This is the mode to use if you are reading an object resource "template" (the 
normal case). 
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stsBadParam resid is a nil resource ID. 

stsResResourceNotFound No resource with the given resId exists. 

stsResNotObjectResource The found resource was a data resource. 

stsResNotFullyRead The msgRestore routine did not read the same amount of data as the msgSave 
wrote. 

msgResWriteObject To write an object to a resource file. 

msgResReadData To read data from a resource file. 

Pseudo code for reading an object resource: 

#define sampleResId MakeWknResId(clsXXX, 17) 

readObj.resId = sampleResId; 

readObj.mode = resReadObjectMany; 

ObjCallRet (msgNewDefaults, clsObject, &readObj.objectNew, status); 

status = ObjCallWarn(msgResReadObject, file, &readObj) ; 

object = readObj .objectNew.uid; 



msgResWriteObject § 

Writes a resource object to a file. 

Takes P_RES_WRITE_OBJECT, returns STATUS. 

tdefine msgResWriteObject MakeMsg(clsResFile, 6) 

typedef struct RES_WRITE_OBJECT { 

RES_WRITE_OBJ_MODE mode; // Duplicate checking mode 

RES_ID resId; // 

OBJECT object; // Object to write 

RES_SAVE_RESTORE_FLAGS sysFlags; // Only for msgResWriteObjectWithFlags 

U16 appFlags; // Only for msgResWriteObjectWithFlags 

U32 sparel; 

} RES_WRITE_OBJECT, *P_RES_WRITE_OBJECT; 

There are two modes that can be applied to writing an object resource, resWriteObjectOnce and 
resWriteObjectMany. 

Setting mode to resWriteObjectOnce, will only write the object to the resource file once (per open). 
This guarantees that all filed references to a given object refer to the same object. This is the mode is 
used by msgResPutObject, and should be used by you if you bypass it and use msgResWriteObject 
directly in a msgSave procedure. There are other uses of it, but they can be very tricky, so make sure you 
read all of the documentation and understand it thoroughly before you try to use this any place other 
than a msgSave procedure. 

Setting mode to resWriteObjectMany, will write a new copy of the object to the resource file whether 
the object has already been written before or not. This is the mode to use if you are writing an object 
resource "template" (the normal case). 

StsBadParam resId is a nil resource ID. 

stsResWriteObjDynamicClass Class of object cannot be dynamic. 

stsResResourceTooBig Tried to write resource bigger than resource file can handle (l6Meg). 

msgResReadObject To read an object from resource file. 

msgResWriteData To write data to a resource file. 
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msgResGetObject 

Reads the filed object resource from the current file position. 

Takes P_OBJECT, returns STATUS. 

tdefine msgResGetObject MakeMsg(clsResFile, 8) 

This should only be called by routines responding to msgRestore. This message is provided as a 
convenience. It eliminates the need for everyone to duplicate the same code and guarantees that the 
parallel operation (msgResPutObject) will work. 

stsResGetNotFromRestore This was sent in a context other than in response to a msgRestore. 

This message is equivalent to this pseudo code: 

STREAM_READ_WRITE fsRead; 
RES_READ_OBJECT resRead; 
STATUS status; 

// Read the object's resource ID from the file. 

fsRead.numBytes = SizeOf (resRead.resId) ; 

fsRead.pBuf = SresRead.resId; 

Ob jCallRet (msgStreamRead, pArgs->file, SfsRead, status); 

// Set up the read resource object request. 

resRead.mode = resReadObjectOnce; 

ObjCallRet (msgNewDefaults, clsObject, &resRead.new, status); 

// Read the object if one was filed, 
if (resRead.resId != resNilResId) { 

ObjCallRet (msgResReadObject, pArgs->file, SresRead, status); 
} 

msgResPutObject 

Writes the object as a filed object resource to the current file position. 

Takes OBJECT, returns STATUS. 

tdefine msgResPutObject MakeMsg(clsResFile, 9) 

This should only be called by routines responding to msgSave. This message is provided as a 
convenience. It eliminates the need for everyone to duplicate the same code and guarantees that the 
parallel operation (msgResGetObject) is done in the correct order. 

stsResPutNotFromSave This was sent in a context other than in response to a msgSave. 

This message is equivalent to this pseudo code: 

STREAM_READ_WRITE fsWrite; 
RES_WRITE_OBJECT resWrite; 
STATUS status; 

if (object != Nil (OBJECT) ) { 

// Assign an appropriate resource ID to the object, 
if (! Ob jectlsDynamic (object) ) { 

resWrite. resid = MakeWknObjResId (object) ; 
} else { 

ObjCallRet ( 

msgResNextDynResId, pArgs->file, &resWrite.resId, status 
); 
} 

// Write the object. 
resWrite. mode = resWriteObjectOnce; 
resWrite. object = object; 
ObjCallRet (msgResWriteObject, pArgs->file, &resWrite, status); 
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} else { 

//No object. 

resWrite.resId = resNilResId; 

} 

// Write the object's resld. 

fsWrite.nuitiBytes = SizeOf (resWrite.resId) ; 

fsWrite.pBuf = &resWrite. resld; 

ObjCallRet (msgStreamWrite, pArgs->file, &fsWrite, status); 



msgResReadObjectWithFlags 

Reads a resource object, passing the supplied flags. 

Takes P_RES_READ_OBJECT, returns STATUS. 

tdefine msgResReadObjectWithFlags MakeMsg(clsResFile, 15) 

Message typedef struct RES_READ_OBJECT { 

l^rgyments RES_READ_OBJ_MODE mode; // Duplicate checking mode 

RES_ID resld; // 

OBJECT_NEW objectNew; // Object passed back in new.uid 

RES_SAVE_RESTORE_FLAGS sysFlags; // Only for msgResReadObjectWithFlags w 

U16 appFlags; // Only for msgResReadObjectWithFlags 3 

U32 spare 1; m 

} RES_READ_OBJECT, *P_RES_READ_OBJECT; 

:omnienfs This is identical to msgResReadObject except that it copies the flag values supplied into all msgRestore 

calls done by this or any object reads that are done recursively from this. 

The values for the sysFlags field are defined by GO and should be examined by any object that needs 
special behavior for any of the defined cases (currently only on copy). 

The values for the app Flags field are defined by an application writer. Great care must be used with 
setting or testing these flags. If the flags from one application are used with a class of a second 
application, disaster can result. E.g. set this field to unless you are very sure you know what you are 
doing. 

tetiirn v«iiie stsBadParam resld is a nil resource ID, 

stsResResourceNotFound No resource with the given resld exists. 

stsResNotObjectResource The found resource was a data resource. 

stsResNotFullyRead The msgRestore routine did not read the same amount of data as the msgSave 
wrote, 

«e Also msgResReadObject Normal message to read an object 

msgResWriteObjectWithFlags The matching write call, 

msgResWriteObjectWithFlags 

Writes a resource object, passing the supplied flags. 

Takes P_RES_WRITE_OBJECT, returns STATUS. 

tdefine msgResWriteObjectWithFlags MakeMsg(clsResFile, 16) 

fesseige typedef struct RES_WRITE_OBJECT { 

i^rguments RES_WRITE_OBJ_MODE mode; // Duplicate checking mode 

RES_ID resld; // 

OBJECT object; // Object to write 

RES_SAVE_RESTORE_FLAGS sysFlags; // Only for msgResWriteObjectWithFlags 
U16 appFlags; // Only for msgResWriteObjectWithFlags 

U32 sparel; 

} RES WRITE OBJECT, *P RES WRITE OBJECT; 
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This is identical to msgResWriteObject except that it copies the flag values supplied into all msgSave 
calls done by this or any object writes that are done recursively from this. 

The values for the sysFlags field are defined by GO and should be examined by any object that needs 
special behavior for any of the defined cases (currently only on copy). 

The values for the appFlags field are defined by an application writer. Great care must be used with 
setting or testing these flags. If the flags from one application are used with a class of a second 
application, disaster can result. E.g. set this field to unless you are very sure you know what you are 
doing. 

stsBadParam resid is a nil resource ID. 

stsResWriteObjDynamicClass Class of object cannot be dynamic. 

stsResResourceTooBig Tried to write resource bigger than resource file can handle (16Meg). 

msgResWriteObject Normal message to write an object. 

msgResReadObjectWithFlags The matching Read call. 



msgResDeleteResource 

Deletes the resource identified by RES_ID. 

Takes RES_ID, returns STATUS. 

#define msgResDeleteResource MakeMsg(clsResFile, 10) 

This marks the resource deleted in the resource file index. The space taken by the resource is reclaimed 
whenever the resource file is compacted. Auto compaction may happen afi:er a resource is deleted. 

Note that this may NOT be called during msgSave or msgRestore. It will appear to work, but the read 
or write will fail. 

StsBadParam resId is a nil resource ID. 

stsResResourceNotFound No resource with the given resId exists. 

Compacts the resource file. 

Takes void, returns STATUS. 

tdefine msgResCompact MakeMsg(clsResFile, 11) 

This message removes all deleted entries from the file and frees any unused space that results. This can 
be called automatically in a couple of ways. See msgNew for an explanation of them. 

stsResCompactlnReadOrWrite Can not compact during read or write. This only happens if 
msgCompact is sent during msgSave or msgRestore. 

msgResFlush 

Flushes the resource file index. 

Takes void, returns STATUS. 

tdefine msgResFlush Ma]ceMsg(clsResFile, 12) 



Comments 
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The resource file keeps track of all objects that have filed themselves in the resource file. It needs this 
information to implement the resReadObjectOnce / resWriteObjectOnce behavior. If you wish to 
override the resReadObjectOnce / resWriteObjectOnce behavior, then flush the resource file. 

Clients rarely use this message. Instead, use the resReadObjectMany / resWriteObjectMany modes with 
msgResReadObject / msgResWriteObject. 

This also sends a msgFSFIush to the file. If all you want to do is flush the file then use msgFSFlush 
instead of msgResFlush. 

msgResReadObject To get info on read once / read many. 

msgResWriteObject To get info on write once / write many. 



Comments 
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msgResEnumResources 

Enumerates resources in a resource file or resource list. 



Takes RES_ENUM, returns STATUS. 

tdefine msgResEnumResources 

typedef struct RES_ENUM { 
U16 max; 

U16 count; 



RES_ENUM_MODE mode; 

UID match; 

P_RES_ID pResId; 

P_RES_FILE pResFile; 



} RES ENUM, *P RES ENUM; 



Mak;eMsg(clsResFile, 13) 



// size of pResId[] and pResFile[] arrays 

// # to pass back in arrays 

// if count > max then memory may be allocated 

// Out: # of valid entries in arrays 

// Enumerate based on what and first/next. 

// key to match on (i.e. class; agent; etc) 

// Out: ptr to array of resource IDs 

// Out: ptr to array of resource file handles 

// Note: if memory was alloc' d for previous 2 

// fields, client should heap free the memory 



This message will enumerate all resources of a given category (based on mode and match) in either a 
single resource file or a resource list. The max and count fields behave as all other enum messages. This 
passes back the resource IDs and files that contain the resources in the pResId and pResFile arrays. 
Mode must always have resEnumNext clear the first time this is called and set subsequent times. Other 
mode flags selectively filter what is being enumerated. 

stsBadParam resEnumNext was specified first time. 

Here is some pseudo-code for enumerating: 

#define resMaxEnums 12 

STATUS status ; 

RES_ENUM rEnum; 

RES_ID enumResIds [resMaxEnums] ; 

RES_FILE enumResFiles [resMaxEnums] ; 

// Enumerate only objects belonging to clsString of the resources. 

rEnum. max = resMaxEnums; 

rEnum. count = resMaxEnums; 

rEnum. mode = resEnumByObjectClass; 

rEnum. match = clsString; 

rEnum. pResId = enumResIds; 

rEnum. pResFile = enumResFiles; 

for (status = stsOK; status == stsOK; ) { 

status = Ob jectCall (msgResEnumResources, resFile, & rEnum ) ; 

for (index = 0; index < rEnum. count; index++) { 
// Process the data, etc, etc 

} 

rEnum. mode |= resEnumNext; 
} 
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msgResNextDynResId 

Allocates the next available dynamic resource ID. 

Takes P_RES_ID, returns STATUS. 

tdefine msgResNextDynResId MakeMsg(clsResFile, 14) 

This message may be used to allocate the next dynamic resource ID available, so that the caller can write 
dynamic items without using msgResPutObject. WARNING: dynamic IDs are based on a 29 bit 
count, and the values are not recycled. If you run out of available counts, this will fail. 

stsResOutOfDynResIds ran out of dynamic resIDs 



ResFile Agent Message 



msgResAgent 

Message sent by resource file to resource agent when forwarding messages. 

Takes P_RES_AGENT, returns STATUS. 

#define msgResAgent MakeMsg(clsResFile, 20) 

iments typedef struct RES_AGENT { 

RES_FILE file; // File containing the resource 

U32 length; // Length of resource entry 

MESSAGE msg; // message passed on to agent 

P_UNKNOWN pArgs; // In-Out: message specific args 

U16 sysVersion; // Min sys version if write 

U16 spare; 

U32 sparel; 

U32 spare2; 

} RES_AGENT, *P_RES_AGENT; 

nients Messages forwarded are msgResReadData, msgResReadObject, msgRes^^iteData, 

msgResUpdateData, msgResWriteObject and msgResUpdateObject. 

For reads, current file pointer will be positioned at resource entry and length of the entry will be passed 
in length field. For writes, current file pointer will be positioned where write should begin. 

Class ResList Messages 

msgNew 

Creates a resource file (search) list object. 

Takes P_RES_LIST_NEW, returns STATUS. Category: class message. 

typedef struct RES_LIST_NEW_ONLY { 

U16 resvdl; 

U16 resvd2; 

} RES_LIST_NEW_ONLY, *P_RES_LIST_NEW_ONLY; 

#define resListNewFields \ 
listNewFields \ 

RES_LIST_NEW_ONLY resList; 

typedef struct RES_LIST_NEW { 

resListNewFields 
} RES LIST NEW, *P RES LIST NEW; 
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clsResList adds no additional msgNew parameters to clsList. There are no messages specific to 
clsResList. It adds additional behavior. 



msgResXxx 

Non-destructive resource file messages. 

Takes P_RES_XXX, returns STATUS. 

Resource lists accept only non-destructive resource file messages (msgResReadData, 
msgResReadObject, msgResReadObjectWithFlags, msgResGetObject, msgResFindResource and 
msgResEnumResources) and forwards the message to each resource file in the list. Resource files that are 
null are skipped and are not considered an error. The resource list stops forwarding the message when 
either all resource files in the list have been exhausted or when one of them responds with a status 
greater than or equal to stsOK. 

Sending msgResEnumResource to a resource file list is special, because it forwards the message to all 
resource files in the list until the list is exhausted. Thus the enumerated data is representative of the 
entire resource list. 

stsRequestNotSupported Msg was not read, find or enum. 

stsListEmpty No valid resource files in the list. 

stsXXX Return values from the resource file messages that are sent to the resource list. 






RESUTIL.H 



This file contains the API definition for the Resource Utility procedures. The functions described in this 
file are contained in RESFILE.LIB. 

tifndef RESUTIL_INCLUDED 
#define RESUTIL_INCLUDED 
tifndef RESFILE_INCLUDED 
tinclude <resfile.h> 
#endif 



Public functions 
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ResUtilLoadObject 

Loads an object from theProcessResList. 
Returns STATUS. 

STATUS EXPORTED ResUtilLoadObject ( 

RES_ID resid, // the resource ID of the object 

P_OBJECT pObject // Out: the object 

); 

This is a short cut to using msgResReadObject to read on object in from theProcessResList. 



ResUtilLoadString 

Loads a string item from theProcessResList. 
Returns STATUS. 

Fuiicfion Prototype STATUS EXPORTED ResUtilLoadString ( 



PP_CHAR ppString, // In/Out: the pointer to the buffer/string 

P_U32 pLength, // In/Out: the length of the buffer/string 

OS_HEAP_ID heap, // Heap to allocate from. 

RES_ID resId // resId for a string 



This is a short cut to using msgResReadData to read a string in from theProcessResList. 

There are two ways of supplying space to load the string into. You can specify a pointer and a length for 
the data passed back (heap = null, *ppString = ptr, *pLength = xx) or you can specify a valid heap from 
which the resource file will allocate memory for the data (heap = heap ID, *ppString - doesn't matter, 
pLength = null or *pLength = doesn't matter). Typically if the size of the data is already known and it is 
small and short lived, then the data is "allocated" on the stack. Otherwise, the data is allocated on behalf 
of a heap. 
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ResUtilLoadListString 

Loads an item from a string list in the application resource list. 
Returns STATUS. 

STATUS EXPORTED ResUtilLoadListString ( 

PP_CHAR ppString, // In/Out: the pointer to the buffer/string 

P_U32 pLength, // In/Out: the length of the buffer/string 

OS_HEAP_ID heap, // Heap to allocate from. 

U32 listGroup, // The list group to select from 

IX_RES_ID listResId // Indexed resid for a string 
); 

This is a short cut to using msgResReadData to read a single string form a string array that is in 
theProcessResList. 

Works just like ResUtilLoadString, except it uses the group and indexed resource ID to construct the 
resource ID of a string list and the index into it. 
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SE1TINGS.H 



clsSettingsNB inherits from clsApp. 

This class defines the Settings Notebook. 

There is only one instance of the Settings Notebook in the system, on the bookshelf. 

The Settings Notebook is an option book. It contains a System Preferences sheet, an Installer sheet, and 
a Status sheet. 

The Preferences sheet contains a group of Preferences cards. These update the system preferences 
resource file (penpoint.res). 

The Installer sheet contains one card for each installation category (apps, preferences, services, etc). Each 
category has an underlying install manager (see instlmgr.h). A card is automatically created when a new 
install manager is created, and deleted when an install manger is destroyed. 

The Installer sheet allows a client to display a particular card and select an item within that card. Here's 
example code which activates the Settings Notebook from the Bookshelf, turns it to the Installer sheet, 
displays a particular card, selects an item within that card, and finally opens the Settings Notebook: 



tinclude <auxnbmgr . h> 
tinclude <instlsht.h> 




{ 

ANM_OPEN_NOTEBOOK 

APP_METRICS 

IUI_SELECT_ITEM 

OPTION_CARD 

IUI_SHOW_CARD 

STATUS 


openNotebook; 

am; 

selectltem; 

oc; 

showCard; 

s; 



ObjectCalKmsgBusySetState, theBusyManager, (P_ARGS) true); 

openNotebook. notebook = anmSettings; 

openNotebook. activateOnly = true; 

Ob jCallRet (msgANMOpenNotebook, theAuxNotebookMgr, &openNotebook, s) ; 

ObjSendUpdateRet (msgAppGetMetrics, openNotebook. uid, Sam, SizeOf(am), s) ; 

oc.tag = taglUIInstallerSheet; 

ObjSendUpdateRet (msgOptionShowCard, am.mainWin, &oc, SizeOf(oc), s) ; 

ObjSendUpdateRet (msgOptionGetTopCard, am.mainWin, &oc, SizeOf(oc), s) ; 

St rcpy { showCard . pCardName , "Applications " ) ; 

Ob jSendRet (msglUIShowCard, oc.win, &showCard, SizeOf (showCard) , s) ; 

strcpy (selectltem. pItemName, appMgrMetrics.name) ; 

ObjSendRet (msglUISelectltem, oc.win, &selectltem, SizeOf (selectltem) 

openNotebook . notebook = anmSettings; 

openNotebook. activateOnly = false; 

Ob jCallRet (msgANMOpenNotebook, theAuxNotebookMgr, &openNotebook, s); 

ObjectCalKmsgBusySetState, theBusyManager, {P_ARGS) false); 
} 

tifndef SETTINGS_INCLUDED 
#define SETTINGS_INCLUDED 

#ifndef APPTAG_INCLUDED 
♦include <apptag.h> 
lendif 



s); 
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Common #clefines and typedefs 



#define tagSettingsPref Sheet MakeTag{clsInstallUISheet, 29) 

#define tagSettingsInstallerSheet MakeTag(clsInstallUISheet, 30) 

#define tagSettingsStatusSheet MakeTag(clsInstallUISheet, 31) 

#define tagSettingsNBPeripheralsOnlconResId tagAppIconBitmap 
tdefine tagSettingsNBPeripheralsOnSmalllconResId tagAppSmalllconBitmap 

#define tagSettingsNBPeripheralsOffSmalllconResId \ 

MakeTag(clsSettingsNBAppWin, 1) 

#define tagSettingsNBPeripheralsOfflconResId \ 

MakeTag(clsSettingsNBAppWin, 2) 

#define tagSettingsPref CmdBar MakeTag(clsSettingsNB, 100) 



Error status codes 



tdefine stsSettingsValueOutOfRange MakeStatus (clsSettingsNB, 1) 

#define stsSettingsFixedValueOutOfRange MakeStatus (clsSettingsNB, 2) 
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This file contains the API definition for clsAppInstallMgr. 

clsAppInstallMgr inherits from clsCodelnstallMgr. 

Manages installation and deinstallation of applications. 

There is a single instance of clsAppInstallMgr in the system; the well-known uid thelnstalledApps. 

thelnstalledApps performs installation and deinstallation of applications and allows you to enumerate 
all of the applications that are currently installed. 

An application is a directory, usually located under \penpoint\app on a given filesystem volume. The 
name of the directory is the name of the application. Within this directory is a .exe and zero or more 
.dlls that make up the application. If a application includes .dlls there must also be a .die file which lists 
all the .dlls and the .exe. The name of the .die file (or the name of the .exe file if there are no .dlls) must 
be the same as the name of the application. If a application is called MAIL, for example, its .die file must 
be named MAIL.DLC. You can use the STAMP.EXE utility to give an application an extended name. Be 
sure to stamp the .die file as well. 

There can also be a service.ini and app.ini file in the application's directory. These specify any additional 
services and applications that should be installed when this application is installed. These services and 
applications are deinstalled when the application is deinstalled. If one of these services or applications is 
already installed it is reference counted, not installed again. 

This directory also contains subdirectories which hold entries in the Help notebook (HELP), stationery 
(STATNRY), tools (ACCESSRY), and any app-specific files that should be copied in when the app is 
installed (MISC). The application's resource file, app. res, is also in this directory. 

The application monitor is responsible for managing the installation of these items. When an app is 
installed its code is loaded and app. res is copied in. The application monitor object is then created and 
completes the installation. You can subclass the application monitor if you need control over the 
installation process. See appmon.h for details. 

An application is installed by sending msglMInstall to thelnstalledApps. Applications are installed 
under user control from the Applications card of the Settings Notebook, \\boot\penpoint\boot\app.ini 
specifies applications that are automatically loaded when the system cold-boots. 

Each installed application has an application directory in the RAM filesystem under \penpoint\sys\app. 
For example, MAIL be in \penpoint\sys\app\MAIL. The application resource file and the MISC 
directory are copied to this directory. 

Each installed application is represented by a handle, in a fashion similar to other install managers (see 
instlmgr.h). This handle is a directory handle onto the application's directory in the RAM filesystem. 

NOTE: THE MESSAGES IN THIS CLASS ARE SENT TO THE MANAGER, NOT TO THE 
HANDLES. 

An application can be deinstalled. Deinstallation removes all traces of an application. 

An application can be deinstalled even if there are running or filed instances of that application in the 
machine. All running instances are shut down (saved, then terminated) when an application is removed. 



514 PENPOINT API REFERENCE 

Part 12 / Installation API 

The application framework will use the Placeholder (MaskApp) class if it tries to start up document with 
a missing application. 

The following superclass messages are not understood by clsAppInstallMgr: 

♦ msglMGetCurrent 

♦ msglMSetCurrent 

♦ msglMSetName 

♦ msglMDup 

The following notification messages are not sent by clsAppInstallMgr: 

♦ msglMNameChanged 

♦ msglMCurrentChanged 
See Also ♦ instlmgr.h 

♦ appmon.h 

#ifndef APPIMGR_INCLUDED 
#define APPIMGR_INCLUDED 

#ifndef CODEMGR_INCLUDED 
# include <codemgr.h> 
#endif 

^ Common #def ines and iypedefs 

msgNew 

Creates a new application installation manager. 

Takes P_AIM_NEW, returns STATUS. Category: class message. 

Arguments typedef struct AIM_NEW { 

installMgrNewFields 
} AIM_NEW, *P_AIM_NEW; 

Commesits There is only one instance of this class, thelnstalledApps, in the system. Clients should never send 

msgNew. 

msgAIMGetMaskClass 

Passes back the mask class. 

Takes P_CLASS, returns STATUS. 

tdefine msgAIMGetMaskClass MakeMsg (clsAppInstallMgr, 6) 

Comments The mask application class is used by the application framework when it tries to start up a document 

with an unavailable application. 

msgAIMSetMaskClass 

Sets the mask class. 

Takes CLASS, returns STATUS. 

♦define msgAIMSetMaskClass MakeMsg (clsAppInstallMgr, 7) 
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Common #defines and typedefs 



Comments The mask application class is used by the application framework when it tries to start up a document 

with an unavailable application. 

This message can be sent at any time; however, the new mask class will only be used for subsequent 
switches. 
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AUXNBIVIGR.H 



This file contains the class definition and methods for clsAuxNotebookMgr. 

clsAuxNotebookMgr inherits from clsObject. 

Manages the system notebooks and documents on the bookshelf. 

There is a single instance of clsAuxNotebookMgr in the system; the well-known aid 
theAuxNotebookMgr. 

The auxiliary notebook manager creates the following items on the bookshelf: 

The Help NotebookSettings NotebookAccessories PalleteStationery NotebookKeyboard 
InstanceConnections Notebook Instancelnbox NotebookOutbox Notebook 

It provides access to those items that are guaranteed to always be on the bookshelf: 

The Help NotebookSettings NotebookAccessories PalleteStationery Notebooklnbox NotebookOutbox 
Notebook 

It allows documents and sections to be created in the Notebooks it manages, and copies documents into 
the Notebooks. It also provides several Stationery-specific functions. 

theAuxNotebookMgr is usually not used by applications, other than to activate and open one of system 
items on the bookshelf 

The document/section creation and copy facilities are used by application installation. 

#ifndef AUXNBMGR_INCLUDED 
tdefine AUXNBMGR_INCLUDED 

tifndef GEO_INCLUDED 

linclude <geo.h> 

tendif 

tifndef FS_INCLUDED 

#include <fs.h> 

tendif 



Common #defines and typedefs 



Which bookshelf item? Used in most messages to theAuxNotebookMgr. Also used as part of the 
definition of the well-known uuids for these items. 



typedef enum ANM_AUX_NOTEBOOK { 

anmReserved = 0, 



anmSettingsNotebook 

anmHelpNotebook 

anrtiStationeryNotebook 

anitil nboxNot ebook 

anmOutboxNotebook 

anmAccessories 



= 1, 
= 3, 
= 4, 
= 5, 
= 6, 
= 7, 



// Never use this value! See 

// anmAttrWhichAuxNB below. 

// Settings Notebook. 

// Help Notebook. 

// Stationery Notebook. 

// Inbox. 

// Outbox. 

//Accessories Pallette. 



} ANM_AUX_NOTEBOOK, *P_ANM_AUX_NOTEBOOK; 
Exist behavior for creating sections and docs. 
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typedef enum ANM_EXIST_BEHAVIOR { 

aniiiExistGenError, 

anmExistDoNothing, 

anmExi St Truncate, 

anmExistGenUnique 
} ANM_EXIST_BEHAVIOR, *P_ANM_EXIST_BEHAVIOR; 

Should a section and/or a notebook entry be added to the stationery menu? 

typedef struct STAT MENU STYLE { 



U16 section 


: 2, 


// Add a section entry. 


notebook 


: 2, 


// Add a notebook entry 


unusedl 


: 12; 


// reserved 



} STAT_MENU_STYLE, *P_STAT_MENU_STYLE ; 

Filesystem Attributes 

Should a given piece of stationery be on the stationery menu? 

tdefine anmAttrStationeryMenu FSMakeFix32Attr(clsAuxNotebookMgr, 1) 

typedef enum ANM_ATTR_STATIONERY_MENU { 

anmNotOnMenu =0, // Same as no attribute. 

anmOnMenu = 1 

} ANM_ATTR_STATIONERY_MENU; 

Should a stationery or tool document not be loaded at install time? This attribute is on the the 
document on the external filesystem. 

#define anmAttrNoLoad FSMakeFix32Attr(clsAuxNotebookMgr, 2) 

typedef enum ANM_ATTR_NO_LOAD { 

anmLoad = 0, // Same as no attribute. 

anmNoLoad = 1 

} ANM_ATTR_NO_LOAD; 

Id tag; used to designate stationery or accessory documents. 

#define anmAttrld FSMakeFix32Attr(clsAuxNotebookMgr, 3) 

Attribute used to tell the difference between an auxiliary notebooks and a data notebooks. Backup 
programs take note. Never backup an auxilary notebook! 

tdefine anmAttrAuxNB FSMakeFix32Attr (clsAuxNotebookMgr, 4) 

typedef enum ANM_ATTR_AUX_NB { 

anmDataNB = 0, // Same as no attribute. 

anmAuxNB = 1 

} ANM_ATTR_AUX_NB; 

Attribute used by clsNBToc to perform special behavior for each auxnb. This attribute is stamped on the 
auxnb s TOC at initialization time. The attribute values are specified in the ANM_AUX_NOTEBOOK 
enum. Note: ANM_AUX_NOTEBOOK must never have a value; indicates no anmAttrWhichAuxNB 
attribute. 

tdefine anmAttrWhichAuxNB FSMakeFix32Attr (clsAuxNotebookMgr, 5) 

Used to get auto-expand behavior of stationery sections. 

tdefine anmAttrExpandStationerySection FSMakeFix32Attr (clsAuxNotebookMgr, 6) 
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Messages 



msgNew 

Creates a new auxiliary notebook manager. 

Takes P_ANM_NEW, returns STATUS. Category: class message. 

♦define auxNotebookMgrNewFields \ 

objectNewFields 

typedef struct ANM_NEW { 

auxNotebookMgrNewFields 
} ANM_NEW, *P_ANM_NEW; 

Note: this is done once and only once in the init routine of this dll to create theAuxNotebookMgr. This 
message must never be called by anyone else! 



^raomenfs 



Comments 



msgANMCreateDoc 

Create a document in one of the auxiliary notebooks. 
Takes P ANM_CREATE DOC, returns STATUS. 



#define msgANMCreateDoc 
typedef struct ANM_CREATE_DOC { 



ANM AUX NOTEBOOK 


notebook; // 


CLASS 


docClass; // 


P STRING 


pPath; // 




// 




// 


P STRING 


pName; // 


U32 


sequence; // 


P STRING 


pBookmarkLabel 


ANM EXIST BEHAVIOR 


exist; // 




// 




// 


BOOLEAN 


putlnMenu; // 




// 


P FS FLAT LOCATOR 


pDestPath; // 




II 




II 


U32 


id; // 


ANM CREATE DOC, *P ANM CREATE DOC; 



MakeMsg(clsAuxNotebookMgr, 1) 

Which auxiliary notebook? 
Document class. 

Path to create doc in, relative to 
base of the aux notebook. pNull 
says to create at top level. 
Name of doc. 

Sequence number to create in front of. 
: // pNull for no bookmark. 
What to do if the doc exists/doesn't 
exist. Note: doc might exist due to 
warm boot. 

If type is stationery, should the doc 
initially be in the stationery menu? 
Out: Location of created doc. 
if pDestPath is pNull then nothing is 
returned. 
Id to tag everything with. is no tag. 



Arguments 



msgANMCreateSect 

Create a section in one of the auxiliary notebooks. 
Takes P_ANM_CREATE_SECT, returns STATUS, 
tdefine msgANMCreateSect 
typedef struct ANM_CREATE_SECT { 



MakeMsgiclsAuxNotebookMgr, 2) 



ANM_AUX_NOTEBOOK 

CLASS 

P_STRING 


notebook; 

sectClass; 

pPath; 


P STRING 
U32 

P_STRING 
ANM EXIST 


BEHAVIOR 


pName; 
sequence; 
pBookmarkL 
exist; 



// Which auxiliary notebook? 
// Section class. 

// Path to create section in, relative to 
// base of the aux notebook. pNull 
// says to create at top level. 
// Name of section. 

// Sequence number to create in front of. 
pBookmarkLabel; // pNull for no bookmark. 

// What to do if the sect exists/doesn't 
// exist. Note: sect might exist due to 
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P_FS_FLAT_LOCATOR pDestPath; 



U32 



id; 



// warm boot. 

// Out: Location of created section. 

// if pDestPath is pNull then nothing is 

// returned. 

// Id to tag everything with. is no tag. 



} ANM CREATE SECT, *P ANM CREATE SECT; 



Argwmenf 



msgANMMovelnDoc 

Move a document into an auxiliary notebook. 
Takes P_ANM_MOVE_COPY_DOC, returns STATUS. 



fdefine msgANMMovelnDoc 

typedef struct ANM_MOVE_ 
ANM_AUX_NOTEBOOK 
FS_LOCATOR 
P STRING 



CLASS 
U32 

P_STRING 

ANM EXIST BEHAVIOR 



COPY_DOC { 
notebook; 
source; 
pPath; 



BOOLEAN 



P FS_FLAT LOCATOR pDestPath; 



U32 
} ANM MOVE COPY DOC, *P 



MakeMsg(clsAuxNotebookMgr, 3) 

// Which auxiliary notebook? 

// Source document. 

// Path to move/copy doc to, relative to 

// base of the aux notebook. pNull 

// says to create at top level. 
defaultClass;// Class to use if source isn't stamped, 
sequence; // Sequence number to move/copy in front 

// of. 
pBookmarkLabel; // pNull for no bookmark, 
exist; // What to do if the doc exists/doesn't 

// exist. Note: doc might exist due to 

// warm boot, 
f orcelnMenu; // If this is stationery, override 

// any local attribute and put it in 

// the stationery menu. 

// Out: Location of destination doc. 

// if pDestPath is pNull then nothing is 

// returned, 
id; // Id to tag everything with. is no tag. 
ANM MOVE COPY DOC; 



msgANMCopylnDoc 

Copy a document into an auxiliary notebook. 
Takes P_ANM_MOVE_COPY_DOC, returns STATUS. 



♦define msgANMCopylnDoc 

typedef struct ANM_MOVE_ 
ANM_AUX_NOTEBOOK 
FS_LOCATOR 
P STRING 



CLASS 
U32 

P_STRING 

ANM EXIST BEHAVIOR 



MakeMsg(clsAuxNotebookMgr, 4) 



COPY_DOC { 
notebook; 
source; 
pPath; 



BOOLEAN 



P_FS_FLAT_LOCATOR pDestPath; 



U32 
} ANM MOVE COPY DOC, *P 



// Which auxiliary notebook? 

// Source document. 

// Path to move/copy doc to, relative to 

// base of the aux notebook. pNull 

// says to create at top level. 
defaultClass;// Class to use if source isn't stamped, 
sequence; // Sequence number to move/copy in front 

// of. 
pBookmarkLabel; // pNull for no bookmark, 
exist; // What to do if the doc exists/doesn't 

// exist. Note: doc might exist due to 

// warm boot. 
forcelnMenu;// If this is stationery, override 

// any local attribute and put it in 

// the stationery menu. 

// Out: Location of destination doc. 

if pDestPath is pNull then nothing is 

returned. 

Id to tag everything with. is no tag. 



id; 



// 
// 
// 



ANM MOVE COPY DOC; 
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msgANMDelete 

Delete a section or document in one of the auxiliary notebooks. 

Takes P_ANM_DELETE, returns STATUS. 

tdefine msgANMDelete MakeMsg{clsAuxNotebookMgr, 7) 

typedef struct ANM_DELETE { 

ANM_AUX_NOTEBOOK notebook; // Which auxiliary notebook? 

P_STRING pPath; // Path of item to delete. 

} ANM_DELETE, *P_ANM_DELETE; 

msgANMDeleteAll 

Delete all the nodes that are identified by 'id'. 

Takes P_ANM_DELETE_ALL, returns STATUS. 

#define msgANMDeleteAll MakeMsg(clsAuxNotebookMgr, 8) 

kgyments typedef Struct ANM_DELETE_ALL { 

ANM_AUX_NOTEBOOK notebook; // Which auxiliary notebook? 

U32 id; //Id. < 

} ANM_DELETE_ALL, *P_ANM_DELETE_ALL; g 

If a node's id attribute or its app class is 'id' then delete it. ^ 

_j 

I* 

V) 

Z 



msgANMGetNotebookPath 

Returns the base path of one of the auxiliary notebooks. 

Takes P_ANM_GET_NOTEBOOK_PATH, returns STATUS. 

tdefine msgANMGetNotebookPath MakeMsg(clsAuxNotebookMgr, 9) 

typedef struct ANM_GET_NOTEBOOK_PATH { 

ANM_AUX_NOTEBOOK notebook; // Which auxiliary notebook? 
P_FS_FLAT_LOCATOR pLocator; // Out: base location of notebook. 

// pNull is returned if the 
// notebook does not exist yet. 
} ANM_GET_NOTEBOOK_PATH, *P_ANM_GET_NOTEBOOK_PATH; 

Note: This will return a path to the table of contents of the notebook. See 
msgANMGetNotebookUUID if you want the actual notebook itself. 



msgANMGetNotebookUUID 

Returns the uuid of one of the auxiliary notebooks. 

Takes P_ANM_GET_NOTEBOOK_UUID, returns STATUS. 

tdefine msgANMGetNotebookUUID MakeMsg(clsAuxNotebookMgr, 10) 

typedef struct ANM_GET_NOTEBOOK_UUID { 

ANM_AUX_NOTEBOOK notebook; // Which auxiliary notebook? 

UUID uuid; // Out: uuid of auxiliary notebook. 

} ANM_GET_NOTEBOOK_UUID, *P_ANM_GET_NOTEBOOK_UUID; 

Note: This is the UUID of the actual notebook. Use msgANMGetNotebookPath to get to the table of 
contents of the notebook. 
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msgANMOpenNotebook 

Activate and optionally open an auxiliary notebook. 

Takes P_ANM_OPEN_NOTEBOOK, returns STATUS. 

tdefine msgANMOpenNotebook MakeMsg(clsAuxNotebookMgr, 11) 

typedef struct ANM_OPEN_NOTEBOOK { 

ANM_AUX_NOTEBOOK notebook; // Which notebook. 

BOOLEAN activateOnly; // Only activate; don't open 

OBJECT uid; // Out: uid of activated or 

// opened auxnb. 

} ANM OPEN NOTEBOOK, *P ANM OPEN NOTEBOOK; 



Private 



msgANMPopUpStationeryMenu 

Pop up the stationery menu at the specified location. 

Takes P_ANM_POP_UP_MENU, returns ST\TUS. 

#define msgANMPopUpStationeryMenu MakeMsg(clsAuxNotebookMgr, 5) 

I typedef struct ANM_POP_UP_MENU { 

XY32 hotSpot; // Where to pop up menu. Coords are 

// relative to destObj. 
OBJECT destObj; // Object to create stationery in front 

// of. 
STAT_MENU_STYLE style; // Menu style. 

} ANM_POP_UP_MENU, *P_ANM_POP_UP_MENU; 

smnients If the user hits one of the menu items create a stationery document in the destination object at the 

hotSpot. 

msgANMGetStationeryMenu 

Passes back the stationery menu. 

Takes P_ANM_GET_MENU, returns STATUS. 

tdefine msgANMGetStationeryMenu MakeMsg(clsAuxNotebookMgr, 6) 

rgunients typedef struct ANM_GET_MENU { 

XY32 hotSpot; // Where to pop up menu. Coords are 

// relative to destObj . 
OBJECT destObj; // Object to create stationery in front 

// of. 
STAT_MENU_STYLE style; // Menu style. 

OBJECT menu; // Out: Stationery menu. 

} ANM_GET_MENU, *P_ANM_GET_MENU; 

inimeiifs This message allows the app framework to add the stationery menu to an existing menu bar. When the 

stationery menu is invoked, stationery is created in destObj at the hotSpot. 

msgANMAddToStationeryMenu 

Add a stationery notebook doc to the stationery menu. 

Takes P_ANM_MENU_ADD_REMOVE, returns STATUS. 

tdefine msgANMAddToStationeryMenu MakeMsg(clsAuxNotebookMgr, 12) 
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Argymeots typedef Struct 2U^_MENU_ADD_REM0VE { 

UUID document; // Dir Index of document to remove. 

} ANM_MENU_ADD_REMOVE, *P_ANM_MENU_ADD_REMOVE; 

msgANMRemoveFromStationeryMenu 

Remove a document from the stationery menu 
Takes P_ANM_MENU_ADD_REMOVE, returns STATUS. 

tdefine msgANMRemoveFromStationeryMenu MakeMsg(clsAuxNotebookMgr, 13) 

Message typedef struct ANM_MENU_ADD_REMOVE { 

Arguments UUID document; // Dir Index of document to remove. 

} ANM_MENU_ADD_REMOVE, *P_ANM_MENU_ADD_REMOVE ; 

msgANMStationeryMenuNameChanged 

Informs the stationery menu that one of its documents has changed name. 
Takes P_ANM_MENU_NAME_CHANGED, returns STATUS. 

tdefine msgANMStationeryMenuNameChanged MakeMsg (clsAuxNotebookMgr, 17) 2 

< 

ArgymeRfs typedef struct ANM_MENU_NAME_CHANGED { g 

UUID document; // Dir Index of document whose name p 

// changed. J 

} ANM MENU NAME CHANGED, *P ANM MENU NAME CHANGED; ^ 

Obsolete 

#define anmAttrPermanent FSMakeFix32Attr (clsAuxNotebookMgr, 0) 

typedef enum ANM_ATTR_PERMANENT { 

anmNotPermanent =0, // Same as no attribute. 

anmPermanent = 1 
} ANM_ATTR_PERMANENT; 

// Next available mess sage number: 18 



W¥ 
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CODEMGR.H 



This file contains the API definition for clsCodelnstallMgr. 

clsCodelnstallMgr inherits firom clsInstallMgr. 

Manages installation and deinstallation of code: applications and services. 

clsAppInstallMgr and clsServicelnstallMgr inherit from this class. 

The following superclass messages are not understood by clsCodelnstallMgr: 

♦ msglMGetCurrent 

♦ msglMSetCurrent 

♦ msglMSetName 

♦ msglMDup 

The following notification messages are not sent by clsCodelnstallMgr: 

♦ msglMNameChanged 

♦ msglMCurrentChanged 

ee Also instlmgr.h 

#ifndef CODEMGR_INCLUDED 
#define CODEMGR_INCLUDED 
#ifndef INSTLMGR_INCLUDED 
#include <instlmgr.h> 
#endif 

Common #clefines and typedefs 

^ Status Codes 

An application or service's name can be a max of nameBuflLength - 4 chars, 
tdefine stsCIMNameTooLong MakeStatus (clsCodelnstallMgr, 0) 

I? Filesystem Attribute Definitions 

Note: Most clients do not deal with attributes direct^. 

Application or service class 

tdefine cimAttrClass FSMakeFix32Attr (clsCodelnstallMgr, 0) 

Application or service program handle 

tdefine cimAttrProgHandle FSMakeFix32Attr (clsCodelnstallMgr, 1) 

Application or service program well-known name 

tdefine cimAttrPrograitiName FSMakeStrAttr (clsCodelnstallMgr, 2) 
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Should this app or service be seen in the installer? This determines whether the user can configure and 
deinstall it, 

#define cimAttrDeinstallable FSMakeFix32Attr(clsCodeInstallMgr, 4) 

typedef enum CIM_ATTR_DEINSTALLABLE { 

cimDeinstallable =0, // Same as no attribute 

ciinNotDeinstallable = 1 
} CIM_ATTR_DEINSTALLABLE; 

Dependent application list 

#define cimAttrAppList FSMakeVarAttr (clsCodelnstallMgr, 6) 

Dependent services list 

#define cimAttrServiceList FSMakeVarAttr (clsCodelnstallMgr, 7) 

Common data structure used by msgCIMTerminateVetoed and msgCIMGetTerminateStatus. 

typedef struct CIM_TERMINATE_VETOED { 

IM_HANDLE handle; 

OBJECT vetoer; // Object that vetoed the terminate. 

STATUS status; // Veto status. 

} CIM TERMINATE VETOED, *P CIM TERMINATE VETOED; 



Messages 



msgCIMGetClassList 

Passes back a list of the classes of the installed applications or services. 
Takes P_LIST, returns STATUS. 

#define msgCIMGetClassList MakeMsg (clsCodelnstallMgr, 1) 

sneiifs CAUTION: The caller must destroy the list object when it is finished using it. 

5 . ^~ msglMGetList (instlmgr.h) Returns a list of handles. 

msgCIMGetClass 

Given a handle, passes back the class. 

Takes P_CIM_GET_CLASS, returns STATUS. 

tdefine msgCIMGetClass MakeMsg (clsCodelnstallMgr, 2) 

imenfs typedef struct CIM_GET_CLASS { 

IM_HANDLE handle; // Handle to get class on. 

CLASS classld; // Out: class. 

} CIM_GET_CLASS, *P_CIM_GET_CLASS; 

msgCIMFindClass 

Returns the handle which references the specified class. 

Takes P_CIM_FIND_CLASS, returns STATUS. 

tdefine msgCIMFindClass MakeMsg (clsCodelnstallMgr, 3) 

jiiienfs typedef struct CIM_FIND_CLASS { 

CLASS classld; // Class to search for. 

IM_HANDLE handle; // Out: Resulting handle. 

} CIM_FIND_CLASS, *P_CIM_FIND_CLASS; 

rn ¥cskje stsNoMatch No handle for this class was found. 
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msgCIMFindProgram 

Finds a item's handle, given its program name. 

Takes P_CIM_FIND_PROGRAM, returns STATUS. 

tdefine msgCIMFindProgram MakeMsg(clsCodeInstallMgr, 22) 

Arguments typedef struct CIM_FIND_PROGRAM { 

P_STRING pName; // Program name to search for 

IM_HANDLE handle; // Out: Resulting handle 

} CIM_FIND_PROGRAM, * P_CIM_FIND_PROGRAM; 

fefyrn ¥«loe stsNoMatch Item not found. 

msgCIMLoad 

Installs code for the item specified. 

Takes P_CIM_LOAD, returns STATUS. Category: descendant responsibility, 
tdefine msgCIMLoad MakeMsg(clsCodeInstallMgr, 4) 

Arguments typedef Struct CIM_LOAD { ^ 

IM HANDLE handle; // Handle of item to load. Z 



1 merits 



} CIM LOAD, *P CIM LOAD; 



O 



This message is sent to subclasses to do the actual work of installing the item. The working directory is d 

set to the source. pArgs->handle references the deactivated item to load. 



z 



msgCIMTerminateOK 

Is this item willing to be terminated? 

Takes P_CIM_TERMINATE_OK, returns STATUS. Category: descendant responsibility. 

tdefine msgCIMTerminateOK MakeMsg(clsCodeInstallMgr, 5) 

typedef struct CIM_TERMINATE_OK { 

IM_HANDLE handle; // Item to ask. 

OBJECT vetoer; // Out: Object which vetoed the terminate. 

} CIM_TERMINATE_OK, *P_CIM_TERMINATE_OK; 

msgCIMTerminate 

Unconditionally terminate this item. 

Takes P_CIM_TERMINATE, returns STATUS. Category: descendant responsibility. 

tdefine msgCIMTerminate MakeMsg(clsCodeInstallMgr, 6) 

typedef struct CIM_TERMINATE { 

IM_HANDLE handle; 

} CIM_TERMINATE, *P_CIM_TERMINATE; 

msgCIMTerminateVetoed 

Somebody vetoed the termination sequence. 

Takes P_CIM_TERMINATE, returns STATUS. Category: descendant responsibility. 

tdefine msgCIMTerminateVetoed MakeMsg{clsCodeInstallMgr, 7) 

typedef struct CIM_TERMINATE { 

IM_HANDLE handle; 

} CIM TERMINATE, *P CIM TERMINATE; 
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msgCIMGetTerminateStatus 

Gets termination status of last item deinstalled. 

Takes P_CIM_TERMINATE_VETOED, returns STATUS. 

tdefine msgCIMGetTerminateStatus MakeMsg(clsCodeInstallMgr, 8) 

Message typedef struct CIM_TERMINATE_VETOED { 

Argwmenfs IM_HANDLE handle; 

OBJECT vetoer; // Object that vetoed the terminate. 

STATUS Status; // Veto status. 

} CIM_TERMINATE_VETOED, *P_CIM_TERMINATE_VETOED; 

Commesits If there was and error then pArgs->vetoer is the object which caused the error; an application instance in 

the case of applications and a service instance in the case of services. pArgs->status is the termination 
status. 



; i¥- **■ 
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DYNTABLE.H 






This file contains the API definition for clsDynamicTableMgr. 

clsDynamicTableMgr inherits from clsObject. 

It allows a tk table to track the comings and goings of installable items. 



Overvie>v 



tkTables (see tktable.h) are typically used to display static tables. However, there are times when clients 
wish to build a tkTable that views a dynamic structure, such as the installed fonts or the currently 
connected filesystem volumes. cisDynamicTableMgr allows a tk table to be dynamically updated as one 
of these things changes. Specifically, clsDynamicTableMgr supports viewing the contents of an install 
manager (see instlmgr.h) and filesystem volumes (see fs.h). 

When the dynamic table manager is first created it generates a tkTable entry for each item in the 
dynamic structure. The label of the tkTable entry is set to the name of the item. The tkTable entry is 
tagged with the uid of the Install Manager handle or the uid of a volume's root directory handle. 

If the specified Install Manager is thelnstalledFonts and the entry class inherits from clsButton then the 
short font id is also stored in' the entry's data field. 

clsDynamicTKTableMgr also supports an optional write-in field that is added to the end of the tk table. 

#ifndef DYNTABLE_INCLUDED 
tdefine DYNTABLE_INCLUDED 

#ifndef CLSMGR_INCLUDED 

tinclude <clsmgr.h> 

#endif 

#ifndef FONT_INSTALL_INCLUDED 

#include <fontmgr.h> 

tendif 



Common #clef ines and typedefs 



Object property tag for entries managed by this class. 

tdefine propDTEntry MakeTag (clsDynamicTableMgr, 1) 

Tag on the fill-in field button, if style.addFilllnField is true. 



tdefine tagDTFilllnField 

Activated/Deactivated display styles 

tdefine dtNoShowDeactivated 
tdefine dtShowDeactivated 



tdefine dtShowDeactivatedAsInactive 2 



MakeTag (clsDynamicTableMgr, 2) 



// Don't show any deactivated items. 

// Show deactivated items same as 

// normal items. 

// Show deactivated with 

// bsLooklnactive. 



typedef struct DYN TABLE STYLE { 



U16 showDeactivated 
autoDestroy 
ignoreRamVolume 
putFontldlnData 
addFilllnField 



2, 
1, 

1, 
1, 
1, 

10; 



// How to deal with deactivated elements. 

// Destroy self when tkTable is freed. 

// Don't show the RAM filesystem volume. 

// Put short font id in entry's data field. 

// Add a blank write-in field. This is a 

// text field inside of a button. 



unused 
U16 sparel; 
} DYN TABLE STYLE, *P DYN TABLE STYLE; 



530 PENPOINT API REFERENCE 
Part 12 / Installation API 



typedef struct DYN_TABLE_NEW_ONLY { 
DYN_TABLE_STYLE style; 
OBJECT installMgr; // Install Mgr, ie. thelnstalledFonts . 

// can also be theFileSystem. 
OBJECT tkTable; // Table to manage. Must be updated 

// after msgRestore via 

// insgDynTableSet Table . 
CLASS entryClass; // Class of tktable entries. 

P_UNKNOWN pNewArgs; // msgNewDefaulted newArgs for 

// entryClass. 
SIZEOF newArgsSize; // Size of newArgs. 

FIM_PRUNE_CONTROL pruneControl; // Prune control if thelnstalledFonts. 
U8 spare [24]; 

} DYN_TABLE_NEW_ONLY, *P_DYN_TABLE_NEW_ONLY; 

♦define dynTableNewFields \ 
objectNewFields \ 
DYN_TABLE_NEW_ONLY dynTable; 

typedef struct DYN_TABLE_NEW { 

dynTableNewFields 
} DYN TABLE NEW, *P DYN TABLE NEW; 



Messages 



msgNew 

Creates a new dynamic table managa. 

Takes P_DYN_TABLE_NEW, returns STATUS. Category: class message. 



ismge typedef struct DYN_TABLE_NEW { 

giimenfs dynTableNewFields 

} DYN TABLE NEW, *P DYN TABLE NEW; 



msgNewDefaults 

Initializes the DYN_TABLE_NEW structure to default values. 

Takes P_DYN_TABLE_NEW, returns STATUS. Category: class message. 

^essoge typedef struct DYN_TABLE_NEW { 

Irgiiments dynTableNewFields 

} DYN TABLE NEW, *P DYN TABLE NEW; 



Sets 



dynTable . Style . showDeactivated = noShowDeactivated; 
dynTable. style. autoDestroy = true; 
dynTable . style . ignoreRamVolume = true; 
dynTable. style. putFontldlnData = true; 
dynTable. style. addFilllnField = false; 



msgDynTableGetTable 

Gets the tkTable we are associated with. 

Takes P_OBJECT, returns STATUS. 

tdefine msgDynTableGetTable MakeMsg(clsDynamicTableMgr, 1) 
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msgDynTableSetTable 

Sets our tkTable. 

Takes OBJECT, returns STATUS. 

tdefine msgDynTableSetTable MakeMsg(clsDynamicTableMgr, 2) 

This must be done whenever this object is restored. It is the client's responsibUty to rehnk the tkTable 
with the dynamic table manager. 

msgDynTableFindButton 

Finds a button in the table which has the specified label. 

Takes P_DYN_TABLE_FIND_BUTTON, returns STATUS. 

tdefine msgDynTableFindButton MakeMsg(clsDynamicTableMgr, 3) 

typedef struct DYN_TABLE_FIND_BUTTON { 

P_STRING pName; // Label name of field to find. 

OBJECT button; // Out: Found button. 

} DYN TABLE FIND BUTTON, *P DYN TABLE FIND BUTTON; E 

_______ ^ 

stsNoMatch Label not found. § 

I 

msgDynTableSetFilllnField ^ 

Sets the fill-in field to a text string. 

Takes P_STRING, returns STATUS. 

#define msgDynTableSetFilllnField MakeMsg (clsDynamicTableMgr, 4) 

stsBadParam There is no fill-in field in the table. 



^^■. 







FONTMGR.H 



This file contains the API definition for clsFontlnstallMgr. 

clsFontlnstallMgr inherits fi:om clsInstallMgr. 

It performs font installation and maintenance. 

There is a single instance of clsFontlnstallMgr in the system; the well-known uid thelnstalledFonts. 

The font manager maintains the installed and deinstalled fonts on the system. The font manager differs 
from a generic install manager in the area of font identification and the system font. 

A font is a structured file. The system comes with several pre-defined font files that are loaded at cold 
boot time. 

Font files typically reside in the \penpoint\font directory on a given filesystem volume. This is not a 
requirement, however. 

Fonts are identified in four ways: 



a font file handle 
a short font ID 
a string font ID 
the name of a font file 



Font file handles are open file handles on to the font files. Much of the install manager interface uses 
these handles. A short font ID is a pre-defined, 1 6 bit value that identifies a specific font. It is a 
compact, specific reference for a particular font. The window system API uses short font IDs. A string 
font ID is a 4 character string version of a short font ID. The font file name is the user-visible name for 
the font. Given a handle, you can get the font file name by sending msglMGetName. Given a short 
font ID, you can get the font file name by sending msgFIMGetNameFromld. 

NOTE: THE MESSAGES IN THIS CLASS ARE SENT TO THE MANAGER, NOT TO THE 
HANDLES. 

A list of all the font handles in the system is available via superclass message msglMGetList. A pruned 
list of the fonts that is appropriate for end-user display is available via msgFIMGetlnstalledlDList. 

The following messages are not understood by clsFontlnstallMgr: 

♦ msglMGetCurrent 

♦ msglMSetCurrent 

♦ msglMDup 

The following notification messages are not sent by clsFontlnstallMgr: 

♦ msglMCurrentChanged 

instlmgr.h 

tifndef FONTMGR_INCLUDED 
♦define FONTMGR_INCLUDED 

#ifndef INSTLMGR_INCLUDED 
#include <instlmgr.h> 
tendif 
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Common #defines and typedefs 

Filesystem attribute definitions 

Note: Most clients do not deal with attributes directlj/^. 

Font ID 

#define fimAttrld FSMakeStrAttr (clsFontlnstallMgr, 0) 

Font ID definitions 

typedef U16 FIM_SHORT_ID, *P_FIM_SHORT_ID; 

typedef struct FIM_LONG_ID { 

U8 pld[5]; 
} FIM_LONG_ID, *P_FIM_LONG_ID; 

FIM_GET_SET_ID is used by msgFIMGetId and msgFIMSetld. 

typedef struct FIM_GET_SET_ID { 

IM_HANDLE handle; // Font handle to get IDs on. 

FIM_SHORT_ID id; // Out: short version of ID. 

FIM_LONG_ID longid; // Out: long ID version. 

} FIM_GET_SET_ID, *P_FIM_GET_SET_ID; 

Messages 

msgNew 

Creates a new font install manager. 

Takes P_FI]VI_NEW, returns STATUS. Category: class message. 

typedef struct FIM_NEW { 
installMgrNewFields 
} FIM_NEW, *P_FIM_NEW; 

There is only one instance of this class, thelnstalledFonts, in the system. Clients should never send 
msgNew. 

msgNewDefaults 

Initializes the FIM_NEW structure to default values. 

Takes P_FIM_NEW, returns STATUS. Category: class message. 



Arqys-Tienfs 



jsssge typedef struct FIM_NEW { 
s installMgrNewFields 

} FIM NEW, *P FIM NEW; 



irciH 



Sets 

installMgr.fileMode 1= fsReadOnly I fsSystemFile; 



msgFIMGetId 

Gets the short and long font IDs, given a handle. 

Takes P_FIM_GET_SET_ID, returns STATUS. 

#define msgFIMGetId MakeMsg (clsFontlnstallMgr, 3) 



iessoge 
rgumesits 



typedef struct FIM_GET_SET_ID { 
IM_HANDLE handle; 

FIM_SHORT_ID id; 
FIM_LONG_ID longid; 

} FIM GET SET ID, *P FIM GET SET ID; 
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// Font handle to get IDs on. 
// Out: short version of ID. 
// Out: long ID version. 



msgFIMSetId 

Set the font file's ID. 

Takes P_FIM_GET_SET_ID, returns STATUS. 

tdefine msgFIMSetId 

typedef struct FIM_GET_SET_ID { 
IM_HANDLE handle; 

FIM_SHORT_ID id; 

FIM_LONG_ID longid; 

} FIM GET SET ID, *P FIM GET SET ID; 



MakeMsg(clsFontInstallMgr, 4) 

// Font handle to get IDs on. 
// Out: short version of ID. 
// Out: long ID version. 



If the short version of the ID is then the long version of the ID is used. 

Note: A font ID is not normally changed. This message is here to allow a tool that edits font IDs to be 
written. 

msgFIMFindId 

Finds a font handle given a short ID. 
Takes P_FIM_FIND_ID, returns STATUS, 
tdefine msgFIMFindId 

typedef struct FIM_FIND_ID { 

FIM_SHORT_ID id; 

IM_HANDLE handle; 

} FIM_FIND_ID, *P_FIM_FIND_ID; 

stsNoMatch font handle not found. 



MakeMsg(clsFontInstallMgr, 5) 



// ID, short form 

// Out: resulting handle 



w'auiiienfs 



msgFIMGetNameFromId 

Passes back font name given an short ID. 

Takes P_FIM_GET_NAME_FROM_ID, returns STATUS. 

tdefine msgFIMGetNameFromId MakeMsg(clsFontInstallMgr, 6) 

typedef struct FIM_GET_NAME_FROM_ID { 

FIM_SHORT_ID id; 

P_STRING pName; // Out: name, max size is nameBufLength 

} FIM_GET_NAME_FROM_ID, *P_FIM_GET_NAME_FROM_ID; 

StsNoMatch short ID not found. 
msglMGetName Gets the name given a handle. 



msgFIMGetlnstalledldList 



Passes back a list of the short IDs of all installed fonts. 

Takes P_FIM_GET_INSrALLED_ID_LIST, returns STATUS. 

tdefine msgFIMGetlnstalledldList MakeMsg(clsFontInstallMgr, 7) 
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typedef enum FIM_PRUNE_CONTROL { 

fimNoPruning = 0, 

fimPruneDupFamilies = flagl, 

fimPruneSymbolFonts = flag2 
} FIM_PRUNE_CONTROL, *P_FIM_PRUNE_CONTROL; 

typedef struct FIM_GET_INSTALLED_ID_LIST { 

FIM_PRUNE_CONTROL prune; // What sort of pruning should be done 

OBJECT list; // Out: list 

} FIM_GET_INSTALLED_ID_LIST, *P_FIM_GET_INSTALLED_ID_LIST; 

This list is pruned so that it is useable as a user pick list. For example, if both Helvetica and Helvetica 
Bold are in the system, only Helvetica is on this list. 

THE CALLER MUST DESTROY THE LIST OBJECT WHEN IT IS FINISHED USING IT. 

msglMGetList Gets a list of all handles. 
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HWXMGR.H 



This file contains the API definition for clsHWXProtoInstallMgr. 
clsHWXProtoInstallMgr inherits fi^om clsInstallMgr. 

It performs handwriting prototype installation and maintenance. 

There is a single instance of clsHWXProtoInstallMgr in the system; the well-known uid 

thelnstalledHWXProtos. 

The hwxproto manager maintains the installed and deinstalled handwriting prototype sets on the 

system, and their relation to the installable handwriting translation engines, which are kept on 

theHWXEngines service manager. The hwxproto manager differs from a generic install manager in the 

area of hwx engine identification and its tie-in with theHWXEngines service manager. 

A handwriting prototype set is a directory which contains engine-specific information. Each installed 

engine on the system must have at least one hwxproto set in thelnstalledHWXProtos in order for it to 

be used. 

also instlmgr.h 

tifndef HWXMGR_INCLUDED 
#define HWXMGR_INCLUDED 
#ifndef INSTLMGR_INCLUDED 
tinclude <instlmgr.h> 
#endif 

Common #clefines and typedefs 

Status Codes 

The hwx engine for this prototype set is not available 

tdefine stsHIMEngineUnavailable MakeStatus (clsHWXProtoInstallMgr, 0) 

Can't change current hwx prototype; hwx engine is in use with it 

tdefine stsHIMCurrentEnginelnUse MakeStatus (clsHWXProtoInstallMgr, 1) 

No training for this handwriting set. 

tdefine stsHIMNoTraining MakeStatus (clsHWXProtoInstallMgr, 2) 

No practice for this handwriting set. 

tdefine stsHIMNoPractice MakeStatus (clsHWXProtoInstallMgr, 2) 



Filesystem attribute definitions 

HWX Engine name 
tdefine himAttrEngineName 



FSMakeStrAttr (clsHWXProtoInstallMgr, 0) 
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Is the engine for this hwxproto available? 

♦define himAttrEngineAvailable FSMakeFix32Attr(clsHWXProtoInstallMgr, 1) 

typedef eniun HIM_ATTR_ENGINE_AVAILABLE { 

hiitiEngineAvailable =0, // Same as no attribute 

himEngineUnavailable = 1 

} HIM_ATTR_ENGINE_AVAILABLE; 

HWX Training window class. This is stamped on the HWX Engine Service class directory. 

#define himAttrTrainingWinClass FSMakeFix32Attr (clsHWXProtoInstallMgr, 3) 

HWX Practice window class. This is stamped on the HWX Engine Service s class directory, 

tdefine himAttrPracticeWinClass FSMakeFix32Attr (clsHWXProtoInstallMgr, 4) 

Gesture Training window class. This is stamped on the Gesture Engine Service's class directory. 

tdefine himAttrGestTrainingWinClass FSMakeFix32Attr (clsHWXProtoInstallMgr, 5) 

Gesture Practice window class. This is stamped on the Gesture Engine Service's class directory. 

tdefine hiinAttrGestPracticeWinClass FSMakeFix32Attr (clsHWXProtoInstallMgr, 6) 



^ «J^' 



Popup Training and Practice tags 



tdefine msgHIMPopUpTraining 
tdefine msgHIMPopUpPractice 
tdefine msgHIMPopUpGestureTraining 
tdefine msgHIMPopUpGesturePractice 
tdefine tagHIMPopUpTraining 
tdefine tagHIMPopUpPractice 
tdefine tagHIMPopUpGestureTraining 
tdefine tagHIMPopUpGesturePractice 
tdefine hlpHIMTrainingButton 
tdefine hlpHIMPracticeButton 
tdefine hlpHIMGestureTrainingButton 
tdefine hlpHIMGesturePracticeButton 



MakeMsg (ClsHWXProtoInstallMgr, 100) 

MakeMsg (ClsHWXProtoInstallMgr, 101) 

MakeMsg (clsHWXProtoInstallMgr, 102) 

MakeMsg (ClsHWXProtoInstallMgr, 103) 

MakeTag (clsHWXProtoInstallMgr, 1) 

MakeTag (ClsHWXProtoInstallMgr, 2) 

MakeTag (ClsHWXProtoInstallMgr, 3) 

MakeTag (clsHWXProtoInstallMgr, 4) 

MakeTag (ClsHWXProtoInstallMgr, 100) 

MakeTag (clsHWXProtoInstallMgr, 101) 

MakeTag (ClsHWXProtoInstallMgr, 102) 

MakeTag (clsHWXProtoInstallMgr, 103) 



Messages 



msgNew^ 

Creates a new handwriting prototype install manager. 

Takes P_HIM_NEW, returns STATUS. Category: class message. 

typedef struct HIM_NEW { 
installMgrNewFields 
} HIM_NEW, *P_HIM_NEW; 

There is only one instance of this class, thelnstalledHWXProtQS, in the system. Clients should never 
send msgNew. 



msgHIMGetEngine 

Gets the name and availability of the engine associated with this hwxprot. 

Takes P_HIM_GET_SET_ENGINE, returns STATUS. 

tdefine msgHIMGetEngine MakeMsg (clsHWXProtoInstallMgr, 1) 
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Arguments typedef struct HIM_GET_SET_ENGINE { 

IM_HANDLE handle; // hwxproto handle to get engine name of. 

P_STRING pEngineName;// Out: Name. Must have at least 

// nameBuf Length bytes allocated. 
BOOLEAN available; // Out: Is the engine available? 

} HIM_GET_SET_ENGINE, *P_HIM_GET_SET_ENGINE; 

Comments Engine names can be up to nameLength characters long. 



msgHIMSetEngine 



l,rgymesif 



Set the hwxproto's engine name. 

Takes P_HIM_GET_SET_ENGINE, returns STATUS. 

#define msgHIMSetEngine MakeMsg(clsHWXProtoInstallMgr, 2) 

typedef struct HIM_GET_SET_ENGINE { 

IM_HANDLE handle; // hwxproto handle to get engine name of. 

P_STRING pEngineName;// Out: Name. Must have at least 

// nameBuf Length bytes allocated. 

BOOLEAN available; // Out: Is the engine available? 

} HIM_GET_SET_ENGINE, *P_HIM_GET_SET_ENGINE; 

Note: This message is rarely used. Typically, handwriting prototype sets have the engine attribute 
stamped on them when they are created, and it is never changed. 

msgHIMAvailabilityChanged 

An hwx proto's engine availability has changed. 

Takes P_HIM_AVAILABILITY_NOTIFY, returns STATUS. Category: observer notification. 

tdefine msgHIMAvailabilityChanged MakeMsg(clsHWXProtoInstallMgr, 20) 

typedef struct HIM_AVAILABILITY_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HANDLE handle; // handle that changed 

BOOLEAN available; // new engine availability state 

} HIM AVAILABILITY NOTIFY, *P HIM AVAILABILITY NOTIFY; 
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This file contains the API definition for clsIniFileHandler. 

clsIniFileHandler inherits firom clsObject. 

Reads and processes a .ini file. 

.ini files are used to ask the system to install multiple applications, services, or any installable entity, A 
.ini file is an ASCII file that contains the path of each item to be installed on a seperate line. Examples 
of .ini files include app.ini (applications) and service.ini (services). 

To process a .ini file, simply create an instance of clsIniFileHandler. The newArgs specify the location of 
the .ini file. The .ini file will be completely processed as part of the msgNew^. Free the ini file handler 
immediately after creating it. 

tifndef INIFILE_INCLUDED 
tdefine INIFILE_INCLUDED 

#ifndef CLSMGR_INCLUDED 
tinclude <clsmgr.h> 
tendif 

#ifndef INSTLMGR_INCLUDED 
tinclude <instlmgr.h> 
tendif 



Messages 



irgomer 



msgNew 

Creates a new ini file processor. 

Takes P_INI_FILE_NEW, returns STATUS. Category: class message. 



typedef struct INI_FILE_STYLE { 
U16 deleteFileWhenDone : 1, 
returnlnstallErrors : 1, 

spare : 11; 

} INI_FILE_STYLE, *P_INI_FILE_STYLE; 

typedef struct INI_FILE_NEW_ONLY { 



// 
// 
// 
// 



INI_FILE_STYLE 
IM_INSTALL_EXIST 

FS_LOCATOR 
OBJECT 

FS_ATTR_LABEL 
OBJECT 



style; 
exist; 

locator; 
manager; 

listAttrLabel; 
listHandle; 



Delete file after processing it. 
Aborts the install and returns error 
status if true. Keeps going if false, 
unused (reserved) 



// What to do if the item already 

// exists. 

// .ini file location. 

// Install manager to send 



// msglMInstalls to. 



OBJECT relDir; 

U8 spare [8]; 

} INI_FILE_NEW_ONLY, *P_INI_FILE_NEW_ONLY; 

tdefine iniFileNewFields \ 
objectNewFields \ 

INI FILE NEW ONLY iniFile; 



List attr; if not needed. 

FS handle for list attr; objNull 

if not needed. 

Relative dir for ini file paths. 
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typedef struct INI_FILE_NEW { 

iniFileNewFields 
} INI FILE NEW, *P INI FILE NEW; 



Comments This message will return after the entire file has been processed. The file is processed by sending 

msglMInstall to the specified install manager for each path in the .ini file. 

pArgs->iniFile.listAttrLabel and pArgs->iniFile.listHandle are passed through to msglMInstall. See 
instlmgr.h for details on msglMInstall. 



msgNewDefaults 

Initializes the INI_FILE_NEW structure to default values. 

Takes P_INI_FILE_NEW, returns STATUS. Category: class message. 

typedef struct INI_FILE_NEW { 

iniFileNewFields 
} INI_FILE_NEW, *P_INI_FILE_NEW; 

Sets 

iniFile.style.returnlnstallErrors = true; 

iniFile.style.deleteFileWhenDone = false; 

iniFile.listAttrLabel = 0; 

iniFile.listHandle = objNull; 

iniFile.exist = imExistReactivate; 
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INSTALL.H 



This file contains definitions for IMProgramlnstall and IMModuleLoad. The fiinctions described in this 
file are contained in INSTALL.LIB. 

APPLICATION DEVELOPERS MUST USE THESE FUNCTIONS INSTEAD OF 
OSProgramlnstall AND OSModuleLoad. 

OSProgramlnstall and OSModuleLoad do not dispatch messages, because they are Ring routines. This 
will cause the system to lock up if the code being loaded needs to send messages to the process that 
installed it, as all applications and services do, 

tifndef INSTALL_INCLUDED 
♦define INSTALL INCLUDED 



IMProgramlnstall 

Low-level .exe installation routine. 
Returns STATUS. 

FotKtioR Prototype STATUS EXPORTED IMProgramlnstall { 



P STRING 



P STRING 



P_OS_PROG_HANDLE 
P_STRING 

P STRING 



) 



pPath, // WorkingDir relative path of 

// .exe or .die file 
pWorkingDir,// WorkingDir relative path of where 

// to set the WorkingDir of the 

// instance O's process 
pProgHandle,// Out: program handle 
pBadName, // Out: if error, dll/exe that was bad 

// Buffer must be nameBuf Length 
pBadRef // Out: If error, reference that was bad 

// Buffer must be nameBuf Length 



IMModuleLoad 

Low-level .dll installation routine. 
Returns STATUS. 



Foncfien Promiype STATUS EXPORTED IMModuleLoad ( 



P STRING 



P STRING 



P_OS_PROG_HANDLE 
P_STRING 

P STRING 



pPath, // WorkingDir relative path of 

// .dll or .die file 
pWorkingDir, // WorkingDir relative path of where 

// to set the WorkingDir of the 

// DLLMainO process 
pProgHandle,// Out: program handle 
pBadName, // Out: if error, dll that was bad 

// Buffer must be nameBuf Length 
pBadRef // Out: If error, reference that was bad 

// Buffer must be nameBuf Length 
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INSTLMGR.H 



This file contains the class definition and methods for clsInstallMgr. 

clsInstallMgr inherits firom clsObject. 

Provides the basic facilities for installing items. 

NOTE: THE MESSAGES IN THIS CLASS ARE SENT TO THE INSTALL MANAGER, NOT TO 
THE HANDLES. 

clsInstallMgr provides almost everything needed to manage installable items. An installable item is 
anything that can be installed and deinstalled on a Penpoint machine, such as fonts, applications, 
services, handwriting prototype sets, etc. You create an instance of clsInstallMgr for each category of 
installable item. Penpoint creates well-known install managers for the following categories at cold boot 
time: 

♦ thelnstalledHWXProtos: Handwriting prototype sets 

♦ thelnstalledPrefs: Preference sets 

♦ thelnstalledPDicts: Personal dictionaries 

In addition there are several well-known install managers that are created from subclasses of 
clsInstallMgr: 

♦ thelnstalledApps: Applications (appimgr.h) 

♦ thelnstalledServices: Services (servimgr.h) 

♦ thelnstalledFonts: Fonts (fontmgr.h) 

clsInstallMgr makes use of the filesystem to keep a database of the installed items. Each item is 
represented by a file or directory handle. This is a big win for items which *are* files or directories; the 
InstallMgr's handle is a handle onto the actual item. There is an extra level of indirection for items 
which are not files. The item's ID (whatever that means for a particular type of item) is stored as an 
attribute of the handle. An item's name is the name of that item's filesystem node. This means that items 
on a given install manager must have unique names. 

An install manager has a base directory in which it keeps its items' filesystem nodes. The createlnitial 
style bit determines whether the install manager creates an initial set of item handles from whatever is in 
this directory when the install manager is first created. 

clsInstallMgr provides an API for installing new items and deinstalling existing items. An item is 
installed fi"om a location on an external filesystem. 

An item can be deinstalled, which removes all traces of the item from the system. 

The install manager maintains a bit which specifies if an item has changed. It is the client's responsibility 
to maintain this bit by sending msglMSetModified when it modifies an item. The install manager will 
remember the time and date that the item was modified. 

Install managers also maintains a "current" item, and provide an API for getting and setting the current 
item. This is used by thelnstalledHWXProtos, thelnstalledPrefs and thelnstalledPDicts to specify 
which handwriting prototype set, preferences, or personal dictionary the system is actively using. A 
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current item is optional; some install managers (thelnstalledApps, thelnstalledServices) do not make 
use of a current item. 

An item can be marked as being "in use". This means that the item cannot be deinstalled. The current 
item is considered to be in use. 

Each install manager can have a verifier object, which it queries whenever installation takes place. The 
verifier object makes sure that the item being installed is valid for this install manager. 

An InstallMgr sends notification to its observers whenever an item is installed, deinstalled, the current 
item changed, etc. Subclasses of clsInstallMgr can turn notification generation on and off with 
msglMSetNotify. Notification is on by default. 

A subset of the notification messages are also sent to any observers of an item's handle. This allows 
clients who are only interested in a particular item to monitor just that item. The messages sent are: 

♦ msglMNameChanged 

♦ msglMInUseChanged 

♦ msglMModifiedChanged 

♦ msglMDeinstalled 

♦ msglMCurrentChanged (sent to both old and new current handles) 

Clients access installable managers via an ObjectCall interface. clsInstallMgr can accommodate 
simultaneous access by multiple clients if the "shared" style bit is set true (the default). This causes it to 
semaphore all of its operations. This semaphore is available to subclasses via msglMGetSema, and 
should be used to protect all subclass messages if multiple clients will be accommodated. clsInstallMgr 
also sets objCapCall on by default. 

There is a well-known, shared list object (see list.h) that is a list of all the install managers in the system. 
This object is called thelnstallManagers. You can observe this list and get notification when an install 
manager is added and removed. See msgListNotifyAddition and msgListNotifyDeletion. 

cIsFontlnstallMgr, cIsAppInstallMgr, and clsServiceMgr inherit from clsInstallMgr. See fontmgr.h, 
appimgr.h and servmgr.h for these classes. 

#ifndef INSTLMGR_INCLUDED 
tdefine INSTLMGR_INCLUDED 

tifndef CLSMGR_INCLUDED 
tinclude <clsmgr.h> 
#endif 

tifndef FS_INCLUDED 
tinclude <fs.h> 
fendif 

tifndef LIST_INCLUDED 
tinclude <list.h> 
tendif 

tifndef TKTABLE_INCLUDED 
tinclude <t]ctable.h> 
tendif 

tifndef OPTION_INCLUDED 
tinclude <option.h> 
tendif 
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Comnton #defines and typedefs 

Handle type 

typedef OBJECT IM_HANDLE, * P_IM_HANDLE ; 

Warning Codes 

Some install manager request has been user cancelled 

tdefine stsIMRequestCancelled MakeWarning(clsInstallMgr, 0) 



Quick Help Tags 



# define appQHInstallMgr 

#define svcQHInstallMgr 

tdefine hwxQHInstallMgr 

tdefine gestQHInstallMgr 

tdefine dictQHInstallMgr 

tdefine fontsQHInstallMgr 

tdefine userPfleQHInstallMgr 



MakeTag(clsInstallUISheet, 32) 
MakeTag(clsInstallUISheet, 33) 

MakeTag(clsInstallUISheet, 34) 
MakeTag{clsInstallUISheet, 35) 

MakeTag(clsInstallUISheet, 36) 
MakeTag{clsInstallUISheet, 37) 
MakeTag{clsInstallUISheet, 38) 



Status Codes 

The item is current, so cannot be removed. 

tdefine stsIMCurrent MakeStatus (clsInstallMgr, 1) 

An item to be installed failed verification. 

tdefine stsIMInvalidltem MakeStatus (clsInstallMgr, 2) 

A new name cannot be created for this item. 

tdefine stsIMUniqueNameFailed MakeStatus (clsInstallMgr, 3) 

The item is in use, so cannot be removed. 

tdefine stsIMInUse MakeStatus (clsInstallMgr, 6) 

The item to be installed is already installed. 

tdefine stsIMAlready Installed MakeStatus (clsInstallMgr, 8) 

An invalid handle was passed in. 

tdefine stsIMBadHandle MakeStatus (clsInstallMgr, 20) 

File System Attribute Definitions 

Note: Most clients do not deal with attributes directly. 

Node's home on an external volume. Absolute path. 

This attribute is used only during installation. 

tdefine imAttrHome FSMakeStrAttr (clsInstallMgr, 0) 

Is this node the current node.? Use IM_ATTR_CURRENT values. 

tdefine imAttrCurrent FSMakeFix32Attr (clsInstallMgr, 2) 

typedef enum IM_ATTR_CURRENT { 

imNotCurrent =0, // Same as no attribute 

imCurrent = 1 

} IM ATTR CURRENT; 



548 PENPOINT API REFERENCE 

Part 12 / Installation API 

Is this node in use? Use IM_ATTR_INUSE values. 

tdefine imAttrlnUse FSMakeFix32Attr{clsInstallMgr, 3) 

typedef enum IM_ATTR_INUSE { 

imNotlnUse =0, // Same as no attribute 

imInUse = 1 

} IM_ATTR_INUSE; 

Has this node been modified? Use IM_ATTR_MODIFIED values. 

♦define imAttrModified FSMakeFix32Attr(clsInstallMgr, 4) 

typedef enum IM_ATTR_MODIFIED { 

imNotModified =0, // Same as no attribute 

imModified = 1 

} IM_ATTR_MODIFIED; 

Ref count. When an item is installed the installer can choose to maintain a reference count if the item is 
already installed. 

#define imAttrRef Count FSMakeFix32Attr (clsInstallMgr, 5) 

Is this item on some other item's dependency list? Use IM_ATTR_DEPENDENT values. 

tdefine imAttrDependent FSMakeFix32Attr (clsInstallMgr, 7) 

typedef enum IM_ATTR_DEPENDENT { 

imNotDependent =0, // Same as no attribute 

imDependent = 1 

} IM_ATTR_DEPENDENT; 

Is this item a system inviolate item? Use IM_ATTR_SYSTEM values. 

tdefine imAttrSystem FSMakeFix32Attr (clsInstallMgr, 8) 

typedef enum IM_ATTR_SYSTEM { 

imNot System =0, // Same as no attribute 

imSystemlnviolate = flagO, 

imSystemNotRenameable = flagl 
} IM ATTR SYSTEM; 



Version string 

#define imAttrVersion 



FSMakeStrAttr (clsAppInstallMgr, 3) 



Debug Flags 

fdefine installDebugFlag 'I' 

Messages 

msgNew 

Creates a new install manager. 

Takes P_IM_NEW, returns STATUS. Category: class message. 



Arguments 



typedef struct IM_STYLE { 
U16 shared 

createlnitial 

autoSetCurrent 

copyOnlnstall 

addToGlobalList 
createlcon 
privatel 
duplicatable 



1, // Provide concurrency protection. 

1, // Create initial list of handles from 

// contents of base directory. 

1, // Choose any item as the initial current 

// setting if no one has current attr set. 

1, // Copy nodes to manager's dir or create 

// handles directly on Install locator. 

1, // Add this instlmgr to thelnstallManagers . 

1, // Create an icon for this install manager. 

1, // Always set this to false. 

1, // Items in this installmgr can be duplicated. 



INSTLMGR.H 
Messages 



549 



usesVersions 

reserved 
U16 sizeCol 

hwxTypeCol 

svcTypeCol 

modifiedCol 

currentCol 

inUseCol 

reservedl 
U32 helpid; 
U16 spare 1; 
U16 spare2; 
} IM_STYLE, *P_IM_STYLE; 

typedef struct IM_NEW_ONLY { 
IM_STYLE 
FS_DIR_NEW_MODE 
FS_FILE_NEW_MODE 
FS LOCATOR 



1, 
7; 
1, 
1, 
1, 
1, 
1, 
1, 
10; 



// Items in this installmgr have versions. 

// Show size column in Settings NB card. 

// Show hwx engine type column. 

// Show service type column. 

// Show modified column. 

// Show current column. 

// Show inUse column. 

// Help tag for installmgr' s Settings NB card. 



style; 
dirMode; 
fileMode; 
locator; 



P_STRING 

P_STRING 

P_STRING 

OBJECT 

OS HEAP ID 



P_TK_TABLE_ENTRY pSettingsMenu; 



U32 
U32 
U32 
U32 
U32 



// Default mode for dir handles. 

// Default mode for file handles. 

// Base directory. InstallMgr will 

// create it if it doesn't exist. 

// Singular name of installer. Must be 

// <= nameLength in size. 

// Plural name of installer. Must be 

// <= nameLength in size. 

// Base path for installable items, 

// (i.e. \penpoint\app) . 

// Verifier object. Can be null. 

// Installmgr heap. Must be global. 

// Can be osInvalidHeapId; instlmgr 

// will use global heap of the task 

// that this object is created in. 

// Additional controls for this 

// installmgr' s Settings NB card. 

settingsMenuSize;// Size (in bytes) of pSettingsMenu. 

unusedl; 

unused2 ; 

unusedS; 

unused4 ; 



pSingularName; 

pName ; 

pInstallPath; 

verifier; 
heap; 



Comments 



} IM_NEW_ONLY, *P_IM_NEW_ONLY ; 

#define installMgrNewFields \ 

objectNewFields \ 

IM_NEW_ONLY installMgr; 

typedef struct IM_NEW { 
installMgrNewFields 
} IM_NEW, *P_IM_NEW; 

The locator field specifies the directory where the managed items live. If this directory does not exist it 
will be created. 



Comment 



msgNewDefaults 

Initializes the IM_NEW structure to default values. 

Takes P_IM_NEW, returns STATUS. Category: class message. 

typedef struct IM_NEW { 
installMgrNewFields 
} IM_NEW, *P_IM_NEW; 

Clients do not normally change the defaults. 
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Zeroes out installMgr and sets 

object. cap |= objCapCall; 
installMgr. style. shared = true; 
installMgr. style. createlnitial = true; 
installMgr. style. updateOK = true; 
installMgr. style. copyOnlnstall = true; 
installMgr. style. addToGlobalList = true; 
installMgr. style. privatel = false; 
installMgr. style. duplicatable = false; 
installMgr. style. createlcon = true; 
installMgr. style. duplicatable = false; 
installMgr. style. usesVersions = false; 
installMgr. style. sizeCol = true; 
installMgr. dirMode = fsUnchangeable; 
installMgr. fileMode = fsSharedMemoryMap; 
installMgr. pInstallPath = pNull; 
installMgr. verifier = objNull; 
installMgr . heap = osInvalidHeapId; 
installMgr. pSettingsMenu = objNull; 
installMgr. sett ingsMenuSize = 0; 



Commersfs 



msgDestroy 

Frees the install manager. 

Takes OBJ_KEY, returns STATUS. 

Note: This message does not destroy the install manager's directory, nor any files/directories in that 
directory. 



tnsgDump 

Prints out the items in the install manager and their state. 
Takes OBJ_KEY, returns STATUS. 



Argyments 



msglMGetStyle 

Passes back the current style settings. 
Takes P_IM_STYLE, returns STATUS. 
tdefine msglMGetStyle 



typedef 


struct IM_STYLE { 






U16 


shared 


1, 


// 




createlnitial 


1, 


// 
// 




autoSetCurrent 


1, 


// 
// 




copyOnlnstall 


1, 


// 
// 




addToGlobalList 


1, 


// 




createlcon 


1, 


// 




privatel 


1, 


// 




duplicatable 


1, 


// 




usesVersions 


1, 


// 




reserved 


7; 




U16 


sizeCol 


1, 


// 




hwxTypeCol 


1, 


// 




svcTypeCol 


1, 


// 




modifiedCol 


1, 


// 




currentCol 


1, 


// 



MakeMsg(clsInstallMgr, 1) 

Provide concurrency protection. 
Create initial list of handles from 

contents of base directory. 
Choose any item as the initial current 

setting if no one has current attr set. 
Copy nodes to manager's dir or create 

handles directly on Install locator. 
Add this instlmgr to thelnstallManagers . 
Create an icon for this install manager. 
Always set this to false. 
Items in this installmgr can be duplicated. 
Items in this installmgr have versions. 

Show size column in Settings NB card. 
Show hwx engine type column. 
Show service type column. 
Show modified column. 
Show current column. 



inUseCol 

reservedl 
U32 helpid; 
U16 sparel; 
U16 spare2; 
} IM STYLE, *P IM STYLE; 
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1, // Show inUse column. 
10; 

// Help tag for installmgr's Settings NB card. 



Messoge 
Argymetits 



msglMSetStyle 

Sets the current style. 

Takes P_IM_STYLE, returns STATUS. 

♦define msglMSetStyle 

typedef struct IM_STYLE { 

U16 shared : 1, 

createlnitial : 1, 

autoSet Current : 1, 

copyOnlnstall : 1, 

addToGlobalList : 1, 

createlcon : 1, 

privatel : 1, 

duplicatable : 1 , 

usesVersions : 1, 

reserved : 7 ; 

U16 sizeCol : 1, 

hwxTypeCol : 1, 

svcTypeCol : 1 , 

modifiedCol : 1, 

currentCol : 1, 

inUseCol : 1, 

reservedl : 10; 

U32 helpid; 

U16 sparel; 

U16 spare2; 
} IM STYLE, *P IM STYLE; 



MakeMsg (clsInstallMgr, 2) 



// Provide concurrency protection. 

// Create initial list of handles from 

// contents of base directory. 

// Choose any item as the initial current 

// setting if no one has current attr set. 

// Copy nodes to manager's dir or create 

// handles directly on Install locator. 

// Add this instlmgr to thelnstallManagers . 

// Create an icon for this install manager. 

// Always set this to false. 

// Items in this installmgr can be duplicated. 

// Items in this installmgr have versions. 

// Show size column in Settings NB card. 

// Show hwx engine type column. 

// Show service type column. 

// Show modified column. 

// Show current column. 

// Show inUse column. 

// Help tag for installmgr's Settings NB card. 



Comments 



msglMGetlnstallerName 

Passes back the install manager's name. 

Takes P_STRING, returns STATUS. 

♦define msglMGetlnstallerName MakeMsg (clsInstallMgr, 3) 

pArgs must point to a nameBufLength buflfer. 

The install manager's name was set at msgNew time in installMgr->pName. 



Comments 



msglMGetlnstallerSingularName 

Passes back the install manager's singular name. 

Takes P_STRING, returns STATUS. 

♦define msglMGetlnstallerSingularName MakeMsg (clsInstallMgr, 51) 

pArgs must point to a nameBufLength bufifer. 

The install manager's name was set at msgNew time in installMgr->pName. 
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msglMGetCurrent 

Passes back the current item's handle. 
Takes P_IM_HANDLE, returns STATUS. 

tdefine msglMGetCurrent MakeMsg(clsInstallMgr, 4) 

Comments Passes back objNull if there is no current handle. 

msglMSetCurrent 

Sets the current item. 

Takes IM_HANDLE, returns STATUS. 

tdefine msglMSetCurrent MakeMsg{clsInstallMgr, 5) 

Comiwenfe The argument is the handle to be made current. It can be objNuIl to indicate that no handle is the 

current one. 

If the handle specified in the argument is already current then nothing is done (no observer message is 
generated). 

Causes the install manager to notijfy observers with msglMCurrentChanged. 



msglMSetlnUse 

Changes an item's in use setting. 

Takes P_IM_SET_INUSE, returns STATUS. 

tdefine msglMSetlnUse MakeMsg(clsInstallMgr, 6) 

Arfynnenfs typedef Struct IM_SET_INUSE { 

IM_HANDLE handle; // Handle of item to set inUse on. 
BOOLEAN inUse; // InUse value. 

} IM_SET_INUSE, *P_IM_SET_INUSE; 

Comments Setting inUse to true means that the item cannot be deinstalled. 

Use msglMGetState to query the value of this field. 

Causes the install manager to notify observers with msglMInUseChanged. 

msglMSetModified 

Changes an item's modified setting. 

Takes P_IM_SET_MODIFIED, returns STATUS. 

tdefine msglMSetModified MakeMsg(clsInstallMgr, 7) 

Arfonnenfs typedef struct IM_SET_MODIFIED { 

IM_HANDLE handle; // Handle of item to set modified on. 

BOOLEAN modified; // Modified value. 

} IM_SET_MODIFIED, *P_IM_SET_MODIFIED; 

Comments Use msglMGctState to query the value of this field. 

Causes the install manager to notify observers with msglMModifiedChanged. 
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msglMGetName 

Get the name of a item. 

Takes P_IM_GET_SET_NAME, returns STATUS. 

#define msglMGetName MakeMsg( els Inst allMgr, 8) 

Arguments typedef struct IM_GET_SET_NAME { 

IM_HANDLE handle; // Handle of item to get /set name on. 
P_STRING pName; // In: (Set) Out: (Get) name. This 

// pointer must reference a naraeBuf Length 
// size buffer. 
} IM_GET_SET_NAME, *P_IM_GET_SET_NAME ; 

msglMSetName 

Sets the name of a item. 

Takes P_IM_GET_SET_NAME, returns STATUS. 

tdefine msglMSetName MakeMsg(clsInstallMgr, 9) 

Messoge typedef struct IM_GET_SET_NAME { < 

Arguments IM_HANDLE handle; // Handle of item to get/set name on. Z 

P_STRING pName; //In: (Set) Out: (Get) name. This p 

// pointer must reference a nameBuf Length ^ 

// size buffer. ^ 

} IM_GET_SET_NAME, *P_IM_GET_SET_NAME ; g 

Comments The name must be a legitimate file name and unique amoung all the items on this install manager. 

Causes the install manager to notify observers with msglMNameChanged. 

Return Voiue stsFSNodeExists An item with this name already exists. 



msglMGetVersion 

Get the version string for this item. 

Takes P_IM_GET_VERSION, returns STATUS. 

#define msglMGetVersion MakeMsg(clsInstallMgr, 37) 

Arguments typedef struct IM_GET_VERSION { 

IM_HANDLE handle; // Handle of item to get version of. 

P_STRING pVersion; // Out: Version string. Pointer must 

// reference a nameBuf Length 

// size buffer. 
} IM_GET_VERSION, *P_IM_GET_VERSION; 

Comments Not all install managers have a version string. pVersion is set to pNull if there is no version. 

msglMGetList 

Passes back a list of all the items on this install managa. 
Takes P_LIST, returns STATUS. 

tdefine msglMGetList MakeMsg(clsInstallMgr, 14) 

Comments The memory for the list object is allocated out of the caller's local process heap. 

CAUTION: Caller must destroy the list object when it is finished using it. 
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rgor 



Slits 



msglMGetState 

Gets the state of a item. 

Takes P_IM_GET_STATE, returns STATUS. 

tdefine msglMGetState 

typedef struct IM_GET_STATE { 

IM_HANDLE handle; 

BOOLEAN current ; 

BOOLEAN reserved; 

BOOLEAN modified; 

BOOLEAN inUse; 
} IM GET STATE, *P IM GET STATE; 



MakeMsg(clsInstallMgr, 16) 



// Handle of item to get state on. 

// Out: Is it the current item? 

// Reserved. 

// Out: Is it modified? 

// Out: Is it in use? 



msglMGetSize 



Returns the size of an item. 

Takes P_IM_GET_SIZE, returns STATUS. 

fdefine msglMGetSize 

typedef struct IM_GET_SIZE { 
IM_HANDLE handle; 
U32 size; 

} IM GET SIZE, *P IM GET SIZE; 



MakeMsg(clsInstallMgr, 17) 



// Handle of item to get size of. 
// Out: size. 



tnsglMInstall 

Installs a new item. 

Takes P_IM_INSTALL, returns STATUS. 

#define msglMInstall 

typedef enum IM INSTALL_EXIST { 



MakeMsg{clsInstallMgr, 18) 



imExi St Update 
imExistReactivate 
imExistGenError 
imExistGenUnique 
imExi stIncRef Count 
} IM_INSTALL_EXIST, *P_IM_INSTALL_EXIST; 

typedef struct IM INSTALL { 



= 0, // Copy new over existing. 

= 1, // Deactivate existing, then activate new. 

= 2, // Return stsIMAlready Installed. 

=3, // Generate a unique name for the new item. 

=4 // Just increment ref count of existing item. 



FS_LOCATOR 

IM_INSTALL_EXIST 
FS_ATTR_LABEL 
OBJECT 
IM HANDLE 



locator; // Location of item on external 

// filesystem. 
exist; // What to do if item already exists. 
listAttrLabel; // Attr list to add install handle to. 
listHandle; // filesystem handle to put attr on. 
handle; // Out: Handle of installed item. 



} IM_INSTALL, *P_IM_INSTALL; 

The install manager derives the item's name from the filesystem location specified in pArgs->locator. 
pArgs->exist controls what happens if an item of the same name as the item to be installed already exists. 

pArgs->listAttrLabel and pArgs->listHandle are used to specify an attr list to which the install handle is 
added. This is used to keep track of sub-apps and sub-services. Set these arguments to if this should 
not be done. 

Causes the install manager to notify observers with msglMInstalled. The install manager also sends 
msglMModifiedChanged if the modified states changed due to the install. 
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Return Value stsIMInvolid Item to be installed does not pass verification. 

stsIMAlreadylnstalled Item already installed and pArgs->exist == imExistGenError. 
stsBadParam pArgs->exist is set to an invalid value. 

msglMDeinstall 

Deinstalls an item. 

Takes P_IM_DEINSTALL, returns STATUS. 

♦define msglMDeinstall MakeMsg( els Inst allMgr, 19) 

Argumersts typedef struct IM_DEINSTALL { 

IM_HANDLE handle; // Item to delete. 
} IM_DEINSTALL, *P_IM_DEINSTALL; 

Comments All traces of the item are removed, including the item's handle. 



letwrn vmlue 



cc*^jrr V<^sue 



stsIMInUse Item is in use; cannot be deinstalled. 



a. 



msglMDup 

Creates a new item that is a duplicate of an existing one. ^ 

^, O 

Takes P_IM_DUP, returns STATUS. S 

#define msglMDup MakeMsg(clsInstallMgr, 23) ^ 

i/i 
4rgumesits typedef struct IM_DUP { "^ 

IM_HANDLE handle; // item to duplicate. 

P_STRING pName; // new name. If pNull then a unique name 

// is generated. 

IM_HMDLE newHandle; // Out: Handle to the new item. 

} IM_DUP, *P_IM_DUP; 

:orr»tierits Causes the install manager to notify observers with msglMInstalled. 

lefyrw Value StsIMAlreadylnstalled An item with pArgs->name already exists. 

msglMFind 

Finds a item's handle, given its name. 

Takes P_IM_FIND, returns STATUS. 

♦define msglMFind MakeMsg(clsInstallMgr, 24) 

Arguments typedef struct IM_FIND { 

P_STRING pName; // Resource name to search for 

IM_HANDLE handle; // Out: Resulting handle 

} IM FIND, *P IM FIND; 



stsNoMatch Item not found. 



msglMGetSema 

Gets the concurrency protection semaphore. 

Takes P_OS_FAST_SEMA, returns STATUS. 

♦define msglMGetSema MakeMsg(clsInstallMgr, 25) 

Comments This message is for subclasses that need to do concurrency protection to their messages. Subclasses 

should get this semaphore and aquire and release it at the beginning and end of their messages. 
Subclasses should use this semaphore instead of creating one of their own in order to avoid race 
conditions. 
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msglMGetDir 

Passes back a directory handle on the install manager's directory. 
Takes P_OBJECT, returns STATUS. 

#define msglMGetDir MakeMsg(clsInstallMgr, 26) 

Comments This dir handle is owned by the install manager; clients must not destroy it! 



msglMGetlnstallPath 

Passes back the install base path. 

Takes P_STRING, returns STATUS. 

♦define msglMGetlnstallPath MakeMsg(clsInstallMgr, 27) 

C0mtfient5 The install base path is an absolute path to the install manager's directory. 

pArgs must point to an fsPathBufLength sized buflfer. 



msglMGetVerifier 

Passes back the current verifier object. 

Takes P_OBJECT, returns STATUS. 

tdefine msglMGetVerifier MakeMsg(clsInstallMgr, 33) 

Comments This object is sent msglMVerijfy whenever an item is attempted to be installed. The verifier should 

return stsOK if the item is valid, stsFailed if it isn't. 



msglMSetVerifier 

Sets the current verifier object. 

Takes OBJECT, returns STATUS. 

tdefine msglMSetVerifier MakeMsg(clsInstallMgr, 34) 

Comments This object is sent msglMVerify whenever an item is attempted to be installed. The verifier should 

return stsOK if the item is valid, stsFailed if it isn't. 



msglMVerify 

Verify the validity of an item that is being installed. 

Takes OBJECT, returns STATUS. 

♦define msglMVerify MakeMsg{ els Inst allMgr, 35) 

Comments This message is sent to an install manager's verifier object whenever an installation is attempted. 

pArgs specifies the node being installed. It is either a file handle or a dir handle. The verifier object 
should determine if the item to be installed is valid, and return stsOK if so, stsFailed if not. 

msglMExists 

Verify the existance of an item that is being installed. 
Takes P_IM_EXISTS, returns STATUS. 

♦define msglMExists MakeMsg(clsInstallMgr, 61) 



Comments 
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typedef struct IM_EXISTS { 

OBJECT source; // In: {File|Dir} handle of item to be installed. 

IM_HANDLE handle; // Out: Handle of item if found. 

} IM_EXISTS, * P_IM_EXISTS; 

This message is self sent whenever an installation is attempted. 

pArgs specifies the node being installed. It is either a file handle or a dir handle. The handler should 
determine if the item to be installed already exists. Returns stsOK if the item is found; stsFailed 
otherwise. 
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msglMUIInstall 



Installs a new item with a user interface. 

Takes P_IM_UI_INSTALL, returns STATUS. 

tdefine msglMUIInstall 

typedef struct IM_UI_INSTALL { 
FS_LOCATOR locator; 

IM_HANDLE handle; 

} IM Ul INSTALL, *P IM Ul INSTALL; 



MakeMsg (clsInstallMgr, 38) 



// Location of item on external 
// filesystem. 
// Out: Handle of installed item. 



Performs msglMInstall, but lets the user decide exist behavior. Pops up a progress note which allows the 
user to cancel the install. Informs the user of successful or unsucessfiil completion. 

Returns msglMInstall statuses. 



Argymenfs 



Refyrn Value 



msglMUIDeinstall 



Deinstalls an item with a user interface. 

Takes P_IM_UI_DEINSTALL, returns STATUS. 

♦define msglMUIDeinstall 

typedef struct IM_UI_DEINSTALL { 

IM_HANDLE handle; 

} IM_UI_DE INSTALL, *P_IM_UI_DEINSTALL; 

Returns msglMDeinstall statuses. 



MakeMsg (clsInstallMgr, 58) 
// Item to deinstall. 



msglMUIDup 

Duplicates and item with a Ul. 
Takes P_IM_UI_DUP, returns STATUS. 

tdefine msglMUIDup 



typedef struct IM_UI_DUP { 

IM_HANDLE handle; 

P STRING pName; 



MakeMsg (clsInstallMgr, 39) 



// item to duplicate. 

// new name. If pNull then a unique name 
// is generated. 
IM_HANDLE newHandle; // Out: Handle to the new item. 
} IM Ul DUP, *P IM Ul DUP; 



ieturn Value 



Returns msglMDup statuses. 
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msglMNameChanged 

The name of a item has changed. 

Takes P_IM_NOTIFY, returns STATUS. Category: observer notification. 

#define msglMNameChanged MakeMsg(clsInstallMgr, 40) 

typedef struct IM_NOTIFY { 

OBJECT manager; // manager that sent notification. 

IM_HANDLE handle; // handle that changed. 

U8 reserved [40] ; 

} IM_NOTIFY, *P_IM_NOTIFY; 

msglMCurrentChanged 

The current item has changed. 

Takes P_IM_CURRENT_NOTIFY, returns STATUS. Category: observer notification. 

tdefine msglMCurrentChanged Ma]ceMsg(clsInstallMgr, 42) 

typedef struct IM_CURRENT_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HANDLE newHandle; // the new current handle 

IM_HANDLE oldHandle; // the previous current handle 

U8 reserved [40]; 

} IM_CURRENT_NOTIFY, *P_IM_CURRENT_NOTIFY; 

msglMInUseChanged 

An item's inUse attribute has changed. 

Takes P_IM_INUSE_NOTIFY, returns STATUS. Category: observer notification. 

tdefine msglMInUseChanged MakeMsg(clsInstallMgr, 43) 

typedef struct IM_INUSE_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HANDLE handle; // handle that changed 

BOOLEAN inUse; // new inUse state 

U8 reserved [ 40 ] ; 

} IM_INUSE_NOTIFY, *P_IM_INUSE_NOTIFY; 

msglMModifiedChanged 

An item's modified attribute has changed. 

Takes P_IM_MODIFIED_NOTIFY, returns STATUS. Category: observer notification. 

#define msglMModifiedChanged MakeMsg(clsInstallMgr, 44) 

typedef struct IM_MODIFIED_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HANDLE handle; // handle that changed 

BOOLEAN modified; // new modified state 

US reserved [40] ; 

} IM MODIFIED NOTIFY, *P IM MODIFIED NOTIFY; 
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msglMInstalled 

A new item was installed. 

Takes P_IM_NOTIFY, returns STATUS. Category: observer notification. 

#define msglMInstalled MakeMsg (clsInstallMgr, 45) 

typedef struct IM_NOTIFY { 

OBJECT manager; // manager that sent notification. 

IM_HANDLE handle; // handle that changed. 

U8 reserved [40]; 

} IM NOTIFY, *P IM NOTIFY; 



msglMDeinstalled 

An item has been deinstalled. 

Takes P_IM_DEINSTALL_NOTIFY, returns STATUS. Category: observer notification. 

#define msglMDeinstalled MakeMsg (clsInstallMgr, 46) 

typedef struct IM_DEINSTALL_NOTIFY { 

OBJECT manager; // manager that sent notification. < 

IM_HANDLE handle; // handle of item that was deinstalled. Z 

U8 pName [nameBuf Length] ; // item name. p 

U8 pVersion [nameBuf Length] ; // item version. 

US reserved [40]; |< 

1 IM_DEINSTALL_NOTIFY, *P_IM_DEINSTALL_NOTIFY; g 

Since the handle is no longer valid when this message is recieved, the pArgs includes all information 
about the item. 



Private 



enfs 



msglMDeactivate 

Deactivate an item. 

Takes P_IM_DEACTIVATE, returns STATUS. 

#define msglMDeactivate MakeMsg (clsInstallMgr, 20) 

typedef struct IM_DEACTIVATE { 

IM_HANDLE handle; // item to deactivate. 

} IM_DEACTIVATE, *P_IM_DEACTIVATE; 

This removes everything but an empty filesytem node with attributes which represents the item. The 
item's handle and attributes remain intact. 

Returns 

stsRequestNotSupported style.copyOnlnstall is false. Install mgrs of this style don't support 
deactivation. 

msglMActivate 

Activate an item by copying it in from disk. 

Takes P_IM_ACTIVATE, returns STATUS. 

#define msglMActivate MakeMsg (clsInstallMgr, 21) 
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Argoments typedef Struct IM_ACTIVATE { 

IM_HANDLE handle; // Item to activate. 
} IM_ACTIVATE, *P_IM_ACTIVATE; 

Coniifients The install manager also sends msglMModifiedChanged if the modified state changed due to the 

activate. 

ietorn Volye stsIMAlreadyActive Item is already active. 

stsIMInvalidltem There is nothing valid out on disk. 



msgAppMgrGetMetrics 

Returns generic icon for this installer. 

Takes P_APP_MGR_METRICS, returns STATUS. 

Install managers understand this message so they can present an icon for use by the disk manager. Install 
managers look for their icons in the system resource file. 

Only the iconBitmap, smalllconBitmap, and name fields of pArgs are filled in. 

msglMAddCards 

Asks the install manager to add option cards for the specified item. 

Takes P_IM_ADD_CARDS, returns STATUS. 

#define msglMAddCards MakeMsg(clsInstallMgr, 56) 

typedef struct IM_ADD_CARDS { 

IM_HANDLE handle; // Item to add cards for. Can be objNull. 

OPTION_TAG optionTag; // msgOptionAddCards argument. 

} IM_ADD_CARDS, *P_IM_ADD_CARDS; 

The handle argument specifies the currently selected item. It may be objNull if there is no selection. 

This message is a superset of msgOptionAddCards. The optionTag argument is exactly the same as that 
for msgOptionAddCards. 

msglMSetNotify 

Turns notification generation on or off. 

Takes BOOLEAN, returns STATUS. 

tdefine msglMSetNotify MakeMsg(clsInstallMgr, 28) 

msglMGetNotify 

Returns notification generation state. 

Takes P_BOOLEAN, returns STATUS. 

♦define msglMGetNotify MakeMsgiclsInstallMgr, 29) 



msglMRemoveHandle 

Removes and frees a handle from our internal list. 



Takes OBJECT, returns STATUS. 

tdefine msglMRemoveHandle MakeMsg{clsInstallMgr, 30) 
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msglMRenameUninstalledltem 

Renames an item on disk. 

Takes P_IM_RENAME_UNINSTALLED, returns STATUS. 

tdefine msglMRenameUninstalledltem MalceMsg(clsInstallMgr, 53) 

Argymeots typedef struct IM_RENAME_UNINSTALLED { 

FS_LOCATOR locator; // Location of item to rename. Must not 

// be an absolute path! 
P_STRING pOldName; // Old name. 

P_STRING pNewName; // New name. 

} IM_RENAME_UNINSTALLED, *P_IM_RENAME_UNINSTALLED; 

msglMGetSettingsMenu 

Sets a pointer to the tkTable entries for the Settings NB menu. 

Takes PP_TK_TABLE_ENTRY, returns STATUS. 

♦define msglMGetSettingsMenu MakeMsg(clsInstallMgr, 54) 

Comments pArgs must be the address of a P_TK_TABLE_ENTRY pointer. < 

z 
o 



msglMGetltemlcon 2 

< 

Gets the icons for a given item. m 

Takes P_IM_GET_ITEM_ICON, returns STATUS. 

♦define msglMGetltemlcon MakeMsg{clsInstallMgr, 57) 

Argymetifs typedef struct IM_GET_ITEM_ICON { 

IM_HANDLE handle; // Handle of item. 

OBJECT iconBitmap; // Out: Icon bitmap. 

TAG iconTag; // Out: Icon's tag in resfile. 

BOOLEAN iconlnSystemRes; // Out: Is this icon in system 

// resource file? 
OBJECT smalllconBitmap; // Out: Small icon bitmap. 
TAG smalllconTag; // Out: Icon's tag in resfile. 

BOOLEAN smalllconlnSystemRes;// Out: Is this icon in system 

// resource file? 
U32 reserved; 

} IM GET ITEM ICON, *P IM GET ITEM ICON; 
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INSTLSHT.H 



This file contains the API definition for clsInstallUISheet. 

clsSettingsNB inherits fi-om clsOption. 

This class defines the Installer sheet in the Settings Notebook. 

The Installer sheet contains one card for each installation category (apps, preferences, services, etc). Each 
category has an underlying install manager (see instlmgr.h). A card is automatically created when a new 
install manager is created, and deleted when an install manger is destroyed. 

The Installer sheet allows a client to display a particular card and select an item within that card. Here's 
example code which activates the Settings Notebook from the Bookshelf, turns it to the Installer sheet, 
displays a particular card, selects an item within that card, and finally opens the Settings Notebook: 



#include <auxnbmgr . h> 
#include <instlsht.h> 




{ 

ANM_OPEN_NOTEBOOK 

APP_METRICS 

IUI_SELECT_ITEM 

OPTION_CARD 

lUI SHOW CARD 

STATUS 


openNotebook; 

am; 

selectltem; 

oc; 

showCard; 

s; 



ObjectCall (msgBusySetState, theBusyManager, (P_ARGS) true); 

openNotebook . notebook = anmSettings; 

openNotebook. act i vat eOnly = true; 

Ob jCallRet (msgANMOpenNotebook, theAuxNotebookMgr, &openNotebook, s) ; 

ObjSendUpdateRet (msgAppGetMetrics, openNotebook. uid, Sam, SizeOf(am), 

oc.tag = tagSettingsInstallerSheet; 

ObjSendUpdateRet (msgOptionShowCard, am.mainWin, &oc, SizeOf(oc), s) ; 

ObjSendUpdateRet (msgOptionGetTopCard, am.mainWin, &oc, SizeOf(oc), s) 

strcpy ( showCard. pCardName, "Applications" ) ; 

Ob j SendRet (msglUI ShowCard, oc.win, SshowCard, SizeOf (showCard) , s) ; 

strcpy (selectltem. pItemName, appMgrMetrics .name) ; 

ObjSendRet (msglUISelectltem, oc.win, Sselectltem, SizeOf (selectltem) , 

openNotebook. notebook = anmSettings; 

openNotebook. act i vat eOnly = false; 

ObjCallRet (msgANMOpenNotebook, theAuxNotebookMgr, &openNotebook, s) ; 

ObjectCall (msgBusySetState, theBusyManager, (P_ARGS) false); 
} 

#ifndef INSTLSHT_INCLUDED 
tdefine INSTLSHT_INCLUDED 

#ifndef TKTABLE_INCLUDED 

#include <tktable.h> 

#endif 

tifndef FS_INCLUDED 

#include <fs.h> 

#endif 

tifndef OPTION_INCLUDED 
#include <option.h> 
#endif 



s); 



s); 
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Messages 



rgumersf 



msglUIShowCard 

Show the specified Installer category card. 
Takes P_IUI_SHOW_CARD, returns STATUS. 
tdefine msglUIShowCard 



MakeMsg(clsInstallUISheet, 1) 



typedef struct IUI_SHOW_CARD { 

CHAR pCardName[nameBuf Length] 



TAG iteitiTag; 

} IUI_SHOW_CARD, * P_IUI_SHOW_CARD; 
stsFailed The specified card was not found. 



// Card Name. These names 
// correspond to installmgr 
// names; ie. Applications, 
// Services, Fonts. See 
// instlmgr.h. 

// If name is of zero length 
// use the tag 



msglUISelectltem 



Set the selection to an item on the current card. 
Takes P_IUI_SELECT_ITEM, returns STATUS. 
tdefine msglUISelectltem 



MakeMsg(clsInstallUISheet, 2) 



typedef struct IUI_SELECT_ITEM { 

CHAR pItemName [nameBuf Length] ; // Name of item to select. 

TAG itemTag; // If name is of zero length 

// use the tag 
} IUI_SELECT_ITEM, * P_IUI_SELECT_ITEM; 

StsFailed The specified item was not found. 



letyrii ¥aioe 



msglUIGetSelectionUID 

Gets the UID of the selection on the current card. 
Takes P_UID, returns STATUS. 
tdefine msglUIGetSelectionUID 
StsFailed There is no selection. 



MakeMsg(clsInstallUISheet, 5) 



msglUIGetSelectionName 

Gets the name of the selection on the current card. 
Takes P_CHAR, returns STATUS. 
tdefine msglUIGetSelectionName 
StsFailed There is no selection. 



MakeMsg(clsInstallUISheet, 6) 



msglUIGetMetrics 

Get installUI metrics. 

Takes P_IUI_METRICS, returns STATUS. 

tdefine msglUIGetMetrics 



MakeMsg(clsInstallUISheet, 3) 
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luments typedef struct IUI_METRICS { 

OBJECT currentCard; // Card displayed. 

CHAR pCurrentCardName [nameBuf Length ] ; // Name of displayed 

// card. 

// Tag of card. 



TAG 


currentCardTag; 


CHAR 


spare [24] ; 


lUI METRICS, 


* P lUI METRICS; 
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PDiCTMGR.H 



This file contains the API definition for clsPDictProtoInstallMgr. 
clsPDictProtoInstallMgr inherits fi-om clsInstallMgr. 

It performs personal dictionary installation and maintenance. 

ft.iso instlmgr.h 

#ifndef PDICTMGR_INCLUDED 
#define PDICTMGR_INCLUDED 
#ifndef INSTLMGR_INCLUDED 
#include <instlingr.h> 
#endif 

Common #defines and typedefs 



Popup Editor messages and tags 



tdefine msgPIMPopUpEditor 
♦define tagPIMPopUpEditor 
tdefine hlpPIMEditorButton 



MakeMsg(clsPDictInstallMgr, 100) 
MakeTag(clsPDictInstallMgr, 1) 
MakeTag(clsPDictInstallMgr, 100) 



Messages 



Arguments 



Comrtienfs 



msgNew 

Creates a new personal dictionary install manager. 

Takes P_PIM_NEW, returns STATUS. Category: class message. 

typedef struct PIM_NEW { 
installMgrNewFields 
} PIM_NEW, *P_PIM_NEW; 

There is only one instance of this class, thelnstalledPDicts, in the system. Clients should never send 
msgNew. 
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SERVIMGR.H 



This file contains the API definition for clsServicelnstallMgr. 
clsServicelnstallMgr inherits fi^om clsCodelnstallMgr. 

Manages installation and deinstallation of services. 

There is a single instance of clsServicelnstallMgr in the system; the well-known uid 
thelnstalledServices. 

thelnstalledServices performs installation and deinstallation of services, allows you to enumerate all of 
the services that are currently installed, and find out their classes. 

See service.h for the messages that a service implementor needs. See servmgr.h for the messages that a 
service client uses to find and open a particular service. 

Services provide non-application fianctionality under PenPoint; typically some form of background 
server or device driver. Examples of services include: device drivers, inbox/outbox transfer agents such as 
fax and e-mail, network protocol stacks, and databases. 

A service is a directory, usually located under \penpoint\service on a given filesystem volume. The name 
of the directory is the name of the service. Within this directory are one or more .dlls that make up the 
service. 

If a service includes more than one .dll there must also be a .die file which lists all the .dlls. The name of 
the .die file (or the name of the .dll file if there is only one .dll) must be the same as the name of the 
service. If a service is called MAIL, for example, its .die file must be named MAIL.DLC. You can use the 
STAMP.EXE utility to give a service an extended name. Be sure to stamp the .die file as well. 

A service can contain an init.dll. This .dll will be loaded, run, and unloaded during service loading. This 
can be used to set up or modify the service's resource file programmatically. A handle to the service's 
resource file is available to init.dll via msgSvcGetClassMetrics. 

When a service is installed, a service directory is created in the RAM filesystem. All of the state for that 
service lives in this directory. 

A service can have an optional MISC directory. This is very similar to an application's MISC directory. 
MISC is used to store static data files that are common to all service instances. The MISC directory will 
be copied into the service directory when the service is installed. You can get to the MISC directory 
from a service instance by getting class metrics, then specifying a path of "MISC" relative to the service's 
directory. 

A service can have a resource file, called service.res. This is similar to an application's app.res file. The 
resource file is automatically copied to the service directory in RAM when the service is installed, and a 
resource file handle is opened on it and stored in the service class metrics. This resource file should 
contain the service's UI components and quick-help resources. Each service's resource file handle is 
added to the well-known resList theServiceResList. Quick-help searches theServiceResList as part of its 
normal operation. Note that theServiceResList is not callable; you must ObjectSend to it. 
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There is an optional INST directory in a service directory, which contains saved service instance state 
nodes. Pre-configured service instances will be created from the nodes in this directory when the service 
is loaded (see service.h for details). 

There can also be a service.ini and app.ini file in the service directory. These specify any additional 
services and applications that should be installed when this service is installed. These services and 
applications are deinstalled when the service is deinstalled. If one of these services or applications is 
already installed it is reference counted, not installed again. 

A service is installed by sending msglMInstall to thelnstalledServices. Services are installed under user 
control from the Services card of the Settings Notebook, or via the pop-up quick installer (see 
qckinstl.h). \\boot\penpoint\boot\service.ini specifies services that are automatically loaded when the 
system cold-boots. 

Each installed service has a service directory in the RAM filesystem, under \penpoint\sys\service. For 
example, service MAIL would have \penpoint\sys\service\mail. The instance state nodes for the service 
are kept in a directory called INST, under this directory. If the service has preconfigured instances then 
they are copied to the INST directory when the service is first installed. 

Each installed service is represented by a handle, in a fashion similar to other install managers (see 
instlmgr.h). This handle is a directory handle onto the service's directory in the RAM filesystem. 

NOTE: THE MESSAGES IN THIS CLASS ARE SENT TO THE MANAGER, NOT TO THE 
HANDLES. 

A service can be deinstalled. Deinstallation removes all traces of a service and decrements the reference 
count for any dependent services or applications. All service instances are removed from their service 
managers and freed when a service is deinstalled. 

Deinstallation only occurs if the main service and all dependent applications and services agree to 
deinstall. A service or application can veto the deinstallation if it chooses. The default behavior for 
services is to veto if any service instance is open (in use). 

The following superclass messages are not understood by clsServicelnstallMgr: 

♦ msglMGetCurrent 

♦ msglMSetCurrent 

♦ msglMSetName 

♦ msglMDup 

The following notification messages are not sent by clsServicelnstallMgr: 

♦ msglMNameChanged 

♦ msglMCurrentChanged 

NOTE: Each service must contain one and only one service class. Don't try and define more than one 
service class in a single service. 

See Also instlmgr.h 

#ifndef SERVIMGR_INCLUDED 
fdefine SERVIMGR_INCLUDED 

tifndef SERVICE_INCLUDED 

#include <service.h> 

#endif 

tifndef CODEMGR_INCLUDED 

#include <codemgr.h> 

#endif 
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Common #defines and iypedefs 

Well-knovsrn filenames 

These are the files created by clsServicelnstallMgr in a service's directory, 
tdefine svcResFileName "service. res" 

Messages 



msgNew 

Creates a new^ service installation manager. 

Takes P_SIM_NEW, returns STATUS. Category: class message. 

typedef struct SIM_NEW { 
installMgrNewFields 
} SIM_NEW, *P_SIM_NEW; 

There is only one instance of this class, thelnstalledServices, in the system. Clients should never send < 

msgNew. § 

msgSIMGetMetrics g 

Gets the specified service class's metrics. 

Takes P_SIM_GET_METRICS, returns STATUS. 

tdefine msgSIMGetMetrics MakeMsg (clsServicelnstallMgr, 1) 

typedef struct SIM_GET_METRICS { 

IM_HANDLE handle; // Handle of service class to get metrics 

// on. 

SVC_CLASS_METRICS metrics; // Out: metrics. 
} SIM_GET_METRICS, *P_SIM_GET_METRICS; 

See service.h for SVC CLASS METRICS. 
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SYSTEM.H 



This file contains the API definition for clsSystem. 

clsSystem inherits firom clsObject. 

Provides information about the system. 

There is a single instance of clsSystem, theSystem. You send all clsSystem messages to theSystem. 

theSystem manages PenPoint booting. If you need to know when PenPoint booting reaches a certain 
stage or is complete then you can observe theSystem and recieve misgBootStateChanged. You can also 
send msgSysGetBootState to find out what stage booting is currently at. 

PenPoint Booting Sequence 



Cold Boot 



Warm Boot 



Kernel 

System Dll Upgrade 

System Dlls reinitialized 

Instance ' s/DLLMain ( ) s rerun 

App Upgrade 

Services Upgrade 

Run Initial App 

Boot Complete 



Kernel 

System Dlls Loaded (boot. die) 

System Apps Installed (sysapp.ini) 

Initial App Installed 

Bookshelf Created 

Services Installed (service.ini) 

Apps Installed (app.ini) 

Run Initial App 

Boot Complete 

This header file defines constants for all the interesting PenPoint filesystem locations that you might be 

tempted to hard-code. Use these defines instead; for example, to set a string to the location where 

PenPoint applications live, use: 

strcpy(pFoo, sysBaseDir "\\" sysInstallableAppDir) ; 
PenPoint defines "live" areas for documents on volumes. The live area is where the volume's bookshelf is. 
Use msgSysGetLiveRoot to access the live area on a volume. 

tifndef SYSTEM_INCLUDED 
#define SYSTEM_INCLUDED 

tifndef APPDIR_INCLUDED 
#include <appdir.h> 
tendif 

tifndef APPMGR_INCLUDED 

#include <appmgr.h> 

tendif 

tifndef UUID_INCLUDED 

tinclude <uuid.h> 

#endif 
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System Debugging Flags 

System debug flag is 'B', values are: 

1 = Enable active doc cache tracing 

2 = Install items from theSelectedVolume at warm boot 
4 = Go into debugger when stdmsg functions are called 
8 = Enable serial port option sheet testing 

800 = Enable showing of the RAM (theSelectedVolume) Volume 

Common #defines and lypedefs 

penpoint.res is invalid. This is checked during cold and warm boot. 

#define stsSysInvalidSystemResFile MakeStatus (clsSystem, 1) 

Penpoint base directory. 

#define sysBaseDir "PENPOINT" 

Filesystem locations off the base Penpoint directory. 

#define sysInstallableFontDir "FONT" 

#define sysInstallablePrefDir "PREFS" 

#define sysInstallableHWXProtDir "HWXPROT" 

#define sysInstallableGestureDir "GESTURE" 

#define sysInstallablePDictDir "PDICT" 

Idefine sysInstallableAppDir "APP" 

#define sysInstallableServiceDir "SERVICE" 

#define sysBootDir "BOOT" 

♦define sysQuicklnstall "QINSTALL" 

#define sysRuntimeRootDir "SYS" 

Filesystem locations off the runtime root. 

#define sysSysAppFile "SYSAPP.INI" 

#define sysAppFile "APP. INI" 

#define sysSysServiceFile "SYSSERV.INI" 

Idefine sysServiceFile "SERVICE.INI" 

tdefine sysCopyFile "SYSCOPY.INI" 

#define sysResFile "PENPOINT.RES" 

#define sysMILResFile "MIL. RES" 

Idefine sysLiveRoot "Bookshelf" 

Idefine sysLoaderDir "LOADER" 

Default initial app (in penpoint\boot\app). 

Idefine sysDefaultlnitialApp "Bookshelf" 

Boot type. 

typedef enum SYS_BOOT_TYPE { 

sysWarmBoot = 1, 

sysColdBoot = 2 

} SYS_BOOT_TYPE, *P_SYS_BOOT_TYPE; 

Boot progess. 

typedef enum SYS_BOOT_PROGRESS { 

sysKernelComplete = 1, 

sysSystemDllsComplete = 2, 

sysSystemAppsInstalled = 3, 

sysInitialAppInstalled = 4, 

sysBookshelfltemsCreated = 5, 

sysServicesInstalled = 6, 

sysApps Installed = 7, 

sysInitialAppRunning = 8, 

sysBootComplete = 9 
} SYS BOOT PROGRESS, *P SYS BOOT PROGRESS; 
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Boot state. 

typedef struct SYS_BOOT_STATE { 

BOOLEAN booted; 

SYS_BOOT_PROGRESS progress; 

SyS_BOOT_TYPE type; 

CLASS initialAppClass; 

} SYS BOOT STATE, *P SYS BOOT STATE; 



// Has booting totally completed? 

// Where are we in the boot cycle? 

// Boot type; warm or cold. 

// Class of the initial app. 



^Messages 



Comments 



msgNew 

Used by PenPoint to create well-known uid theSystem. 
Takes P_SYS_NEW, returns STATUS. Category: class message. 

typedef struct SYS_NEW_ONLY { 

U32 unusedl 

U32 unused2 

U32 unusedS 

U32 unused4 

} SYS_NEW_ONLY, *P_SYS_NEW_ONLy 

Idefine systemNewFields \ 

objectNewFields \ 

SYS_NEW_ONLY system; 

typedef struct SYS_NEW { 

systemNewFields 
} SYS_NEW, *P_SYS_NEW; 

This message should never be called by anybody else. 



Comments 



msgSysGetBootState 

What stage of booting is the system in? 
Takes P_SYS_BOOT_STATE, returns STATUS. 
#define msgSysGetBootState 

typedef struct SYS_BOOT_STATE { 

BOOLEAN booted; 

SYS_BOOT_PROGRESS progress; 

SYS_BOOT_TYPE type; 

CLASS initialAppClass; 

} SYS BOOT STATE, *P SYS BOOT STATE; 



MakeMsg(clsSystem, 1) 



// Has booting totally completed? 

// Where are we in the boot cycle? 

// Boot type; warm or cold. 

// Class of the initial app. 



This message allows callers to determine the current state of system booting. 
msgSysBootStateChanged Observer message sent at each stage. 



msgSysGetRuntimeRoot 

Returns a dir handle onto the root of the Penpoint runtime area. 

Takes P_OBJECT, returns STATUS. 

tdefine msgSysGetRuntimeRoot MakeMsg{clsSystem, 2) 

Comments Penpoint maintains all of its runtime information in one area of the filesystem on the "selected" volume 

(theSelectedVolume). This message returns a directory handle onto the root of this area. 

NOTE: Caller must free the handle when finished. 
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msgSysGetLiveRoot 

Returns an appDir handle onto the root of a volume's live document area. 

Takes P_SYS_GET_LIVE_ROOT, returns STATUS. 

tdefine msgSysGetLiveRoot MakeMsg(clsSystem, 3) 

Arguments typedef struct SYS_GET_LIVE_ROOT { 

OBJECT volHandle; // Handle onto volume in question. 

OBJECT liveRoot; // Out: appDir handle to live root on 

// the volume. 
} SYS_GET_LIVE_ROOT, *P_SYS_GET_LIVE_ROOT; 

Comtnenfs Live Penpoint documents (those that can be activated) are stored within the live area of a volume. This 

message returns the root of the live area for a given volume, 

pArgs->volHandle is a filesystem handle onto the volume in question. This handle can be on any 
location of the volume. You can also use the root directory handle for a volume. Use theSelectedVolume 
if you want to get the live area within the filesystem that Penpoint stores its on-machine documents in. 

NOTE: Caller must free the pArgs->liveHandle when finished. 

Return ¥«i«e stsFSNodeNotFound No live root on this volume. 

msgSysIsHandleLive 

Determines if a filesystem handle is within the live document area. 

Takes P_SYS_IS_HANDLE_LIVE, returns STATUS. 

tdefine msgSysIsHandleLive MakeMsg(clsSystem, 4) 

Arguments typedef Struct SYS_IS_HANDLE_LIVE { 

OBJECT handle; // Handle onto the node in question. 

BOOLEAN live; // Out: Is it in the live area? 

} SYS_IS_HANDLE_LIVE, *P_SYS_IS_HANDLE_LIVE; 

Comments Penpoint maintains live documents within a particular point in the directory heirarchy of each volume. 

This message determines whether a filesystem handle is within the live area of its volume. 

ieturrs Voloe stsFSNodeNotFound No live root on the handle's volume. 



msgSysCreateLiveRoot 

Create a new live root on a volume. 

Takes P_SYS_CREATE_LIVE_ROOT, returns STATUS. 

tdefine msgSysCreateLiveRoot MakeMsg(clsSystem, 5) 

Argymenfs typedef struct SYS_CREATE_LIVE_ROOT { 

OBJECT volHandle; // Handle onto volume in question. 

CLASS rootClass; // Class of app which should run on the 

// live root directory. 
} SYS_CREATE_LIVE_ROOT, *P_SYS_CREATE_LIVE_ROOT; 

Comments Penpoint maintains live documents within a particular point in the directory heirarchy of each volume. 

This message creates a new live root on a volume if one doesn't already exist. If the live root already 
exists it creates an instance of the app over whatever is there currently. Use msgSysGetLiveRoot if you 
want to check for an existing live root. 
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Messages 



msgSysGetVersion 

Returns the system version number. 
Takes P_U16, returns STATUS. 

tdefine msgSysGetVersion MakeMsg(clsSystem, 6) 

Comments This message allows callers to determine the current PenPoint system version number. 

msgSysGetSecurityObject 

Gets the current security object. 
Takes P_OBJECT, returns STATUS. 

tdefine msgSysGetSecurityObject MakeMsg(clsSystem, 31) 

Comments Returns objNull if there is no current security object. 

msgSysSetSecurityObject 

Sets the current security object. 3| 

Takes P_SYS_SET_SECURITY_OBJECT, returns STATUS. O 

tdefine msgSysSetSecurityObject MakeMsg(clsSystem, 32) ^ 

l^rguments typedef struct SYS_SET_SECURITY_OBJECT { g 

OBJECT securityObject; // New security object. 

OBJ_KEY oldKey; // Object key for old security 

// object. 
} SYS_SET_SECURITY_OBJECT, *P_SYS_SET_SECURITY_OBJECT; 

Comments If a security object already exists then it is destroyed, using the key specified in the arguments. If it 

refuses to be destroyed then the new security object will not be set. 

The security object will be sent msgSysPowerOn and msgSysPowerOff when the power goes on and 
off. At shutdown, msgSysPowerO£F is sent to the security object after msgSysPowerOfif is sent to power 
button observers and after msgAppSave is sent to applications. At power up, msgSysPowerOn is sent to 
the security object before msgSysPowerOn is sent to power button observers. 

msgSysPowerOn and msgSysPowerOff are sent when the machine is suspended/ resumed, or shutdown 
and swap-booted. However, these messages are not sent when a warm-boot occurs. A warm-boot 
destroys all processes and objects. The service or application that owns the security object will be 
restarted in the warm-boot case. Security objects must handle the warm-boot case. For example, if the 
security object is created by the app monitor, the app monitor will receive msgAppInit when the 
application is first installed and msgRestore on all warm-boots. 

At power down, anything painted on the screen by the security object will not appear immediately, but 
will appear on the screen when it is restored at power on time. If the security object wishes to display a 
window on top of all other windows, it should observe theSystem for msgBootStateChanged to 
determine when booting is complete. 

At power on, the security object may choose to veto the powering on of the system by sending 
msgPMSetPowerState to thePowerMgr to turn off power, 

ieturn ¥a!ye stsProtectionViolation old security object refused to be destroyed. 
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msgSysGetCorrectiveServiceLevel 

Gets the corrective service level. 

Takes P_STRING, returns STATUS. 

#define msgSysGetCorrectiveServiceLevel MakeMsg( els System, 33) 

The corrective service level is a string of up to maxNameLength characters. 



msgSysSetCorrectiveServiceLevel 

Sets the corrective service level. 

Takes P_STRING, returns STATUS. 

#define msgSysSetCorrectiveServiceLevel MakeMsg(clsSystein, 34) 

ifieiits The corrective service level is a string of up to maxNameLength characters. 

Notification Messages 

msgSysBootStateChanged 

The system has reached another stage of booting. 

Takes P_SYS_BOOT_STATE, returns STATUS. Category: observer notification. 

#define msgSysBootStateChanged MakeMsg(clsSystem, 10) 

soge typedef struct SYS_BOOT_STATE { 

imenfs BOOLEAN booted; // Has booting totally completed? 

SYS_BOOT_PROGRESS progress; // Where are we in the boot cycle? 

SYS_BOOT_TYPE type; // Boot type; warm or cold. 

CLASS initialAppClass; // Class of the initial app. 

} SYS_BOOT_STATE, *P_SYS_BOOT_STATE; 

iiieiits This message is sent to all observers of theSystem whenever another stage of booting is attained. If you 

are just interested in whether the system has completed booting or not, look at the pArgs-> booted 
boolean. 
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HWXSERV.H 



This file contains the API definition for clsHWXEngineService. 
clsHWXEngineService inherits from clsService. 

Provides default behavior for handwriting engine services. 



tifndef HWXSERV_INCLUDED 
♦define HWXSERV_INCLUDED 

tifndef SERVICE_INCLUDED 
#include <service.h> 
#endif 



^Messages 



msgNew 

Creates a new service object. 

Takes P_HWX_SVC_NEW, returns STATUS. Category: class message. 

Arguments typedef Struct HWX_SVC_NEW_ONLY { 

U32 unusedl; 

U32 unused2; 

U32 unusedS; 

U32 unused4; 

} HWX_SVC_NEW_ONLY, *P_HWX_SVC_NEW_ONLY; 

tdefine hwxServiceNewFields \ 
serviceNewFields \ 
HWX_SVC_NEW_ONLY hwxService; 

typedef struct HWX_SVC_NEW { 

hwxServiceNewFields 
} HWX SVC NEW, *P HWX SVC NEW; 



imenfs 



msgHWXSvcCurrentChanged 

The current handwriting prototype set has changed. 

Takes P_HWX_SVC_CURRENT_CHANGED, returns STATUS. 

tdefine msgHWXSvcCurrentChanged MakeMsg (clsHWXEngineService, 1) 

typedef struct HWX_SVC_CURRENT_CHANGED { 

OBJECT newHandle; 

OBJECT oldHandle; 

} HWX_SVC_CURRENT_CHANGED, *P_HWX_SVC_CURRENT_CHANGED; 

The user has switched to or from a handwriting prototype set that uses this engine. See hwxmgr.h and 
instlmgr.h for details on handwriting prototype set management. 

pArgs->newHandle and pArgs->oldHandle provide the handles of the new and old prototype sets. 
objNull means that the new/former prototype set used some other engine. 
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MILSERV.H 



This file contains the API definition for clsMILService. The functions described in this file are 
contained in milserv.lib. 

clsMILService inherits firom clsService. 

Provides default behavior for MIL services. 

MIL services are PenPoint device drivers. They represent a MIL device, which represents a piece of 
hardware. A MIL service sits between a MIL device and the rest of PenPoint. 

A MIL service is typically composed of a Ring part, which interfaces to the MIL, and a Ring 3 part, 
which interfaces to the rest of PenPoint. 

MIL service instances are created automatically by PenPoint. Never send msgNew to a MIL Service class 
yourself] Each MIL device contains a deviceld, which is the class of the MIL service that should be 
created for it. PenPoint scans the MIL at power-up time and whenever a MIL service installed, and 
creates one MIL service for each unit of each device. 

The MIL service writer can find out the logical id of the device it represents by self-sending 
msgMILSvcGetDevice. 

A MIL service can install a MIL extension if necessary. The new MIL device is installed into the MIL 
when the MIL service is installed, and removed from the MIL when the MIL service is deinstalled. Use 
the InstallMILDeviceO function in your DLLMainQ to do this. 

You must also let the service framework know about a service by sending msgSvcClassInitService to 
your service class in DLLMain(). Here's an example: 

STATUS EXPORTED DLLMain (void) 
{ 

SVC_INIT_SERVICE init Service; 

STATUS s; 

// Initalize classes. 

StsRet (ClsMILServicelnit , s) ; 

// Include if it is necessary to install MIL extensions. 

InstallMILDevice(&deviceInfo) ; 

// Initialize service. This creates MIL service instances. 

memset (initService . spare, , sizeof (initService . spare) ) ; 

init Service. autoCreate = true; 

initService . serviceType = 0; 

initService. initServiceFlags = 0; 

ObjCallRet (msgSvcClassInitService, clsTestService, &initService, s) ; 

return stsOK; 
} // DllMain 
See project MILSVC for a template for creating MIL services. 

#ifndef MIL_SERVICE_INCLUDED 
♦define MIL_SERVICE_INCLUDED 

#ifndef GO_INCLUDED 
♦include <go.h> 
#endif 
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fifndef SERVICE_INCLUDED 
#include <service.h> 
#endif 

#ifndef MIL_INCLUDED 
#include <mil.h> 
#endif 

Common #defiiies and typedefs 

Did this service install MIL devices? 

tdefine svcMILAttrlnstalledDevice FSMakeFix32Attr(clsMILService, 1) 

The MIL device that this mil service is associated with. 



typedef struct MIL_SVC_DEVICE { 



TAG 


unitResourceTag; 


UID 


conflictGroup; 


U16 


logicalld; 


U16 


unit; 


U8 


reserved [12] ; 



// resource tag into mil. res 

// conflict group mil svc is on 

// mil device logical id to use 

// mil device unit number to use 



} MIL SVC DEVICE, *P MIL SVC DEVICE; 



Functions 



InstallMILDevice 

Install a MIL device. 

Returns STATUS. 

¥umf'mn Promtype STATUS EXPORTED InstallMILDevice ( 

P_MIL_DEVICE_INFO pDevicelnfo, // Installable MIL device info. 

U32 reservedl, // Set this to 

U32 reserved2) ; // Set this to 

ComiTients This routine should used to install one or more MIL devices. These devices will be automatically- 

deinstalled when the MIL service is deinstalled. 

This routine *must* be called in the service's DLLMainQ, after the classes are created but beft)re 
msgSvcClassInitService is sent. 



Class Messages 



rg«mi 



msgNew 

Creates a new MIL service object. 

Takes P_MIL_SVC_NEW, returns STATUS. Category: class message. 

typedef struct MIL_SVC_NEW_ONLY { 

MIL_SVC_DEVICE device; 

U32 unusedl; 

U32 unused2 ; 

U32 unused3; 

U32 unused4; 

} MIL_SVC_NEW_ONLY, *P_MIL_SVC_NEW_ONLY; 

fdefine milServiceNewFields \ 
serviceNewFields \ 

MIL SVC NEW ONLY milSvc; 
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Class Messages 



typedef struct MIL_SVC_NEW { 

milServiceNewFields 
} MIL SVC NEW, *P MIL SVC NEW; 



This message should never be sent by dients. PenPoint automatically creates all MIL service instances by 
scanning the MIL. 



msgNewDefaults 

Initializes the MIL_SVC_NEW structure to default values. 

Takes P_MIL_SVC_NEW, returns STATUS. Category: class message. 

iessoge typedef struct MIL_SVC_NEW { 

rgumeots milServiceNewFields 

} MIL_SVC_NEW, *P_MIL_SVC_NEW; 

xnmenfs Sets 

pArgs->svc.style.exclusiveOpen = true; 

pArgs->svc. style. checkOwner = true; 

Note pArgs->svc.style.connectStyle will be set automatically to 

reflect underlying MIL device's auto-detection facilities. It w^ill 

be set to svcAutoDetect if milDevFiagDetachable is true, 

svcNoAutoDetect if milDevFli^Detachable is false. 

Note pArgs->milSvc. device will be set automatically from the MIL. 12 



msgSvcSetConnected 

Sets connection state of self 

Takes P_SVC_GET_SET_CONNECTED, returns STATUS. 

Comments 'P_SVC_GET_SET_C0NNECTED' Structure is defined in service.h. 

This message is self-sent whenever a MIL service thinks that it's connection state has changed. This 
message should be sent even when a mil service isn't sure if it is connected (due to possible interference 
from other mil services in its conflict group). 

If the mil service isn't in a conflict group then the message is sent to ancestor. If it is in a conflict group 
then the following will occur: 

if (pArgs->connected == true) { 

1 . msgCGPollConnected is sent to the conflict group manager. 

2. The conflict group manager sends msgMILSvcAreYouConnected to allservices in the conflict group 

(including the one that self-sent msgSvcSetConnected). 

3. The conflict group manager decides which service really shouldbe connected and sends 

msgMILSvcConnectionStateResolved to all services. This tells which service (if any) has been 
chosen to be the connected one. MIL services should restart their connection detection logic if 
nobody is currently connected. 

4. Default behavior for msgMILSvcConnectionStateResolved is to sendmsgSvcSetConnected to 

ancestor if a change of state is indicated. MIL services must *always* send 
msgMILSvcConnectionStateResolved to ancestor. 
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} else { 

1 . msgSvcSetConnected is sent to ancestor. 

2. msgCGInformDisconnected is sent to the conflict group manager. 

3. Tlie conflict group manager sends msgMILSvcConnectionStateResolvedto all mil services except the 

mil service that sent the msgSvcSetConnected message. MIL services should restart their connection 
detection logic. 

} 
See Also msgSMConnectedChanged (servmgr.h) 

^ cIsMILService Functionality Available to 
Subclasses 

msgMILSvcGetDevice 

Returns MIL device associated with this service. 

Takes P_MIL_SVC_DEVICE, returns STATUS. 

#define msgMILSvcGetDevice MakeMsg(clsMILService, 1) 

Message typedef struct MIL_SVC_DEVICE { 

Argomerifs TAG unitResourceTag; // resource tag into mil. res 

// conflict group mil svc is on 
// mil device logical id to use 
// mil device unit number to use 

} MIL_SVC_DEVICE, *P_MIL_SVC_DEVICE; 

msgMILSvcSetDevice 

Sets MIL device associated with this service. 
Takes P_MIL_SVC_DEVICE, returns STATUS. 
#define msgMILSvcSetDevice MakeMsg(clsMILService, 2) 

srtesscjge typedef struct MIL_SVC_DEVICE { 

Irgumenfs TAG unitResourceTag; // resource tag into mil. res 

UID conflictGroup; // conflict group mil svc is on 

U16 logicalld; // mil device logical id to use 

U16 unit; // mil device unit number to use 

U8 reserved [12]; 

} MIL_SVC_DEVICE, *P_MIL_SVC_DEVICE; 

:omments Note: This message is almost never used. Usually a MIL service is associated with the device that is set at 

msgNew time, and never changed. This message is included for completeness and very special 
circumstances. 

msgMILSvcInstalledMILDevice 

Is this MIL service targeting an installed MIL device? 
Takes pNulI, returns STATUS. 

#define msgMILSvcInstalledMILDevice MakeMsg(clsMILService, 3) 

lomments Returns stsOK if it is, stsFailed if it is not. 



UID 


conflictGroup; 


U16 


logicalld; 


U16 


unit; 


U8 


reserved [12] ; 
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Descendant Responsibility Messages 



msgMILSvcAddToConflictManager 

Add this service instance to a conflict group manager. 

Takes P_MIL_SVC_ADD_TO_CONFLICT_MANAGER, returns STATUS. 

#define msgMILSvcAddToConflictManager MakeMsg(clsMILService, 8) 

Irgymenfs typedef Struct MIL_SVC_ADD_TO_CONFLICT_MMAGER { 

OBJECT manager; 

} MIL_SVC_ADD_TO_CONFLICT_MANAGER, *P_MIL_SVC_ADD_TO_CONFLICT_MANAGER; 

ZommenH This message is used to add a MIL service to a conflict group manager, 

W Descendant Responsibility Messages 

msgMILSvcPowerOff 

The power is about to be turned off. 

Takes pNull, returns STATUS, 

tdefine msgMILSvcPowerOff MakeMsg{clsMILService, 4) 

imnmenis This message is sent after all other power off messages are sent. MIL services must *not* observe the 

power button to get power notification. 

MIL services should save any hardware-specific state that must be restored when the power is applied. 



lO 



tt 



misgMILSvcPowerOn y 

The power has just come on. 

Takes pNuU, returns STATUS. 

#define msgMILSvcPowerOn MakeMsg(clsMILService, 5) 

This message is sent before all other power on messages are sent. MIL services must *not* observe the 
power button to get power notification. 

MIL services should restore any hardware-specific state that was saved when the power was 
disconnected. 



msgMILSvcAreYouConnected 

Do you think you are connected? 

Takes P_MIL_SVC_ARE_YOU_CONNECTED, returns STATUS. 

tdefine msgMILSvcAreYouConnected MakeMsg(clsMILService, 6) 

Arsumeofs Enuml6 (MIL_SVC_ARE_YOU_CONNECTED) { 

msYes = 0, 

msMaybe = 1, 

msNo = 2 

}; 

Commenti This message is sent to all members of a conflict group whenever any service thinks it has become 

connected. It allows all members of the conflict group to participate in deciding who is really connected. 

Default superclass behavior is to return msMaybe. 
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msgMILSvcConnectionStateResolyed 

Tells a MIL service who was chosen to be connected. 

Takes U16, returns STATUS. 

tdefine msgMILSvcConnectionStateResolved MakeMsg(clsMILService, 7) 

Comments The pArgs is the logical id of the service that was chosen to be connected. It is set to maxU16 if nobody 

is connected. 

Default superclass behavior is to send msgSvcSetConnected to ancestor if a change of state is indicated. 

MIL services must always send msgMILSvcConnectionStateResolved to ancestor. 

msgMILSvcStartConnectionProcessing 

It is ok to start connection processing. 
Takes pNulI, returns STATUS. 

#define msgMILSvcStartConnectionProcessing \ 

MsgNoError(MakeMsg(clsMILService, 9)) 

:emm€Rts This message is sent after booting is complete. MIL services should not start their connection processing 

until they receive this message. 
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SERVCONF.H 



This file contains the API definition for clsMILConflictGroupMgr. 

clsMILConflictGroupMgr inherits firom clsServiceMgr. 

Provides definition of conflict group managers. 

A conflict group manager is automatically created for each conflict group in the MIL when one or more 
MIL service instances are created for the MIL devices which are part of that conflict group. The uid of 
the conflict group manager is that of the conflict group itself. In other words, if there is a conflict group 
identified with the tag theMILConflictGroup4, then the conflict group manager will have a well-known 
uid of MILConflictGroup4. 

A conflict group manager is very much like a service manager. All of the MIL service instances that 
represent devices in the conflict group are on the conflict group manager. Each service instance is also 
made an observer of the conflict group manager. 

The conflict group manager keeps track of which MIL service owns the conflict group. The owning 
service is the only one that is permitted to actually use one of the devices in the conflict group. 

#ifndef SERVCONF_INCLUDED 
tdefine SERVCONF_INCLUDED 

tifndef SERVICE_MANAGER_INCLUDED 

♦include <servmgr.h> 

tendif 



Messages 



Comments 



msgNew 

Creates a new conflict group manager. 

Takes P_S]VI_NEW, returns STATUS. Category: class message. 

This message should *never* be called by clients. Conflict group managers are automatically created. 
The new args must always be the same as for a service manager. 



msgCGGetOwner 

Gets the current owner of the conflict group. 
Takes P_CG_GET_OWNER, returns STATUS. 
tdefine msgCGGetOwner 

typedef struct CG_GET_OWNER { 
OBJECT owner; 

U8 reserved [16]; 

} CG GET OWNER, *P CG GET OWNER; 



MakeMsg (clsMILConflictGroupMgr, 1) 
// Out: owner. 



Comments 



If no one owns the conflict group, 'objNuU' will be returned in the owner field. 
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msgCGSetOwner 

Sets a new conflict group owner. 

Takes P_CG_SET_OWNER, returns STATUS. 

tdefine msgCGSetOwner MakeMsg(clsMILConflictGroupMgr, 2) 

Arguments typedef struct CG_SET_OWNER { 

OBJECT owner; // New owner. 

} CG_SET_OWNER, *P_CG_SET_OWNER; 

Comiiients "owner" can be objNull to specify that this conflict group has no owner. 

Old and new owners will recieve service messages which allow them to veto the ownership change and 
informs them that the change has taken effect. The message sequence is as follows: 

1 . msgSvcOwnerAquireRequested is sent to the new owner. pArgs->ownedService is set to the conflict 
group. The new owner can veto the owner change by returning a status of anything other than 
stsOK or stsNotUnderstood. msgCGSetOwner returns with the abort status. 

2. msgSvcOwnerReleaseRequested is sent to the old owner. pArgs->ownedService is set to the conflict 
group. The old owner can can veto the owner change by returning a status of anything other than 
StsOK or StsNotUnderstood. msgCGSetOwner returns with the abort status. 

3. msgSvcOwnerReleased is sent to the old owner. 

4. msgSvcOwnerAquired is sent to the new owner. 

5. msgCGOwnerChanged is sent to all observers of this conflict group manager, includding all of the 
service instances on this manager. 

Metum Value stsBadObject New owner is not an object. 

stsBadAncestor New owner has invalid ancestor. 

See Mso service.h, for definition of msgSvc... messages. 

msgCGPoUConnected 

Polls all the services in the conflict group to see who is connected. 

Takes pNuU, returns STATUS. 

#define msgCGPoUConnected MakeMsg{clsMILConflictGroupMgr, 3) 

Comments A conflict group manager recieves this message when any service within the conflict group thinks it 

might be connected. The conflict group manager sends msgMILSvcAreYouConnected to each service. 
It then sends msgSvcConnectionStateResoIved to each service, choosing one of the services as the 
connected one. 

msgCGInformDisconnected 

Tells all the services in the conflict group that a disconnect happened. 

Takes pNull, returns STATUS. 

♦define msgCGInformDisconnected MakeMsg(clsMILConflictGroupMgr, 4) 

Commesifs A conflict group manager recieves this message when the connected service within the conflict group 

decides it is disconnected. The conflict group manager sends msgSvcConnectionStateResoIved to each 
service, specifying that nobody is connected. 
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Notification Messages 



Tags 



msgCGOwnerChanged 

A conflict group's owner has changed. 

Takes P_CG_OWNER_NOTIFY, returns STATUS. Category: observer notification. 

tdefine msgCGOwnerChanged MakeMsg(clsMILConflictGroupMgr, 10) 

Arguments typedef Struct CG_OWNER_NOTIFY ( 

OBJECT conflictGroup; // conflict group whose owner changed. 

OBJECT oldOwner; // old owner. 

OBJECT owner; // new owner. 

} CG OWNER NOTIFY, *P CG OWNER NOTIFY; 



#define tagConflictChoice MakeTag (clsMILConf lictGroupMgr, 1) 
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SERVICE.H 



This file contains the API definition for clsService. 
clsService inherits from clsStream. 
Provides default behavior for services. 



Introduction 



All non-application functionality under Penpoint is expressed as a service. If what you w^ant to do does 
not fit the application model (documents created via Stationery or Accessories, subclass of clsApp, etc) 
then it should be a service. Some examples of services are: device drivers, inbox/outbox transfer agents 
such as fax and e-mail, network protocol stacks, and device drivers. 

Service instances are automatically organized onto service managers. A service manager represents a 
category of service, such as Printers or Serial Devices. All of the service instances in a given category are 
can be used interchangeably; that is, they all support the API that is required to be in that category. 
Clients access service instances via service managers. See servmgr.h for details. 

Each service instance has a text name, which is how it is uniquely identified. Clients use this name to 
identify a service instance on a service manager. A service instance's name is specified at msgNew time. 
Names must be unique for all services on the same service manager, and all services of the same class. 

There are two exclusivity models for services: services that require exclusive access by a single client, and 
services that allow multiple clients simultaneous access. Services provides default behavior for arbitrating 
ownership of exclusive access services. 

Multiple access services can either be shared (each client gets back the uid of the service when they open 
the service) or multi-user (each client gets back a different object when they open the service). 

Service instances can optionally maintain state. By default each service instance has a node in the 
filesystem. clsService will automatically recreate service instances from their state files when PenPoint is 
rebooted. Also, service instances can be saved and restored from external disks by moving their state 
nodes on and off the machine. 

A service instance can have an optional "target". A target is some other service instance. If a service has a 
target, the service superclass takes care of remembering what the target points at. Typically, data flows 
from one service instance to next, going down the target chain. Control information, such as when a 
physical device is becomes connected, flows up the target chain. 

A service is implemented as an installable DLL. Service instances are either created in the DLLMain() of 
the service DLL, created dynamically after the service has been installed, or created from pre-configured 
instance state nodes when the service is first installed. See servimgr.h for a description of how services are 
installed and deinstalled, and how a service is organized on disk. 
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Writing A Basic Service 

A minimal service that does not save state or use a target must handle just one superclass message: 
msgNewDefaults. There are four fields v^hich need to be filled in: 

pArgs->svc.style.exclusiveOpen - Is this an exclusive access service?>svc.style.openClass - Is this a 
multi-user service?>svc.pManagerList - List of service managers to add to.>svc.numManagers 
- Number of managers on the list. 

Project BASICSVC is a template for a minimal service. Use it as a guide. 

Writing a Service That Saves State 

clsService maintains an open handle on a service s state node. By default the state node type is a file and 
the open handle is an instance of clsFileHandle. Both of these things can be overridden in your 
msgNew^Defaults handler. 

Services must decide for themselves when they need to update their state node. They should always 
maintain enough state to be able to survive a reboot. There is no explicit Save/Restore messages for 
services; A SERVICE MUST UPDATE ITS STATE NODE WHENEVER ITS STATE CHANGES. 

When its time to save state, self-send msgSvcGetHandle to get your state node handle. Self-send 
msgSvcSetModified when you complete updating state. These are the only messages that you will need 
to use for this type of service. 

Service instances will be automatically recreated when a warm boot occurs. The msgNew arguments to 
clsService include the locator of the state node. Service instances must check to see if this node is 
non-empty then a warm boot is happening, and the service must recreate itself from the state node. 

State nodes can be copied out to disk, then reloaded the next time the service class is installed, or 
reloaded one at time. clsService will automatically create a service instance for each state node at this 
time using the same mechanism as warm boot recovery. There is no difference between warm boot 
recovery and creation from a pre-configured state node copied in at installation time, as far as the service 
is concerned. 

Writing a Service That Has A Target 

Services can also bind and open other services. In fact, this is such a common situation that clsService 
provides lots of support for this. Each service can have a target, which refers to some other service. 
When the service is first created the default behavior is to attempt to bind to the target. clsService will 
automatically open the target when the service is opened if the autoOpen style bit is true. 

A service becomes a client of its target. All client observer notifications and ownership messages from a 
service's target are sent to the service. 

A service's target is usually set at msgNew time, and can be changed anytime after with 
msgSvcSetTarget. msgSvcGetTarget gets a service instance's target. 

Typically a service will open its target when a client opens it, using msgSvcOpenTarget. 
msgSvcCloseTarget should be used to close the target. 

Services also support the notion of being connected. Most hardware services can detect whether their 
hardware is connected or disconnected. Each service has a state bit which says whether it is connected or 
not. When the hardware changes connection state the service sends msgSVCSetConnected to itself, 
which notifies everyone who is bound to that service. 
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Non-hardware services automatically change their connection state when their targets change 
connection state. Thus, connection state propogates up from the hardware to all services that are bound 
to that hardware. 

A hardware service for a device that cannot auto-detect connection is always in the connected state. 

Project TESTSVC provides a template for a service that deals with a target. 

Advanced Features 

Services that can provide both global and service instance option cards. A global option sheet sets 
configuration information for the entire service. It is invoked when the user calls for options of a service 
from the Service card of the Installer, Services can add additional cards to the global option sheet. 

Service instance option sheets allow the user to set the configuration of particular instance. For example, 
the serial service provides a card which allows the user to set baud rate, parity, etc. Services should 
update their state node when the user applies a change to the option sheet. There is no default service 
instance option card. 

Services should respond to the standard option sheet protocol (msgOptionAddCards, 
msgOptionRefreshCard, etc) if they wish to provide option cards. See option. h for details. The option 
sheet messages are either sent as class messages for global options or normal instance messages for 
instance options. 

A service's configuration information can also be queried and set programmatically via 
msgSvcGetMetrics and msgSvcSetMetrics. A service must be able to respond to these messages at any 
time, and should update its state node when its metrics are changed. The Get/SetMetrics messages are 
generic; they allow a client to save and restore metrics independently of the size or contents of the 
metrics. This allows a client to have absolutely no knowledge of the internals of a service. The client can 
ask the user to set configuration options, then save and restore these configuration options via the 
generic Get/Set messages. 

Service instances can have icons associated with them in the same fashion as documents. Create icons 
using tagAppIconBitmap and tagAppSmalllconBitmap and put them in the service resource file. This is 
done in the same manner as applications. 

Services and Tasking 

A service, just like any other object, is owned by some task. However, all services must be callable from 
outside the owning task (objCapCall is always true for service instances). Service authors must take this 
into account. Services must either use explicitly-created global heaps or instance data; never store data in 
a local heap or the shared process heap. 

If the service is not exclusive access or multi-user, anyone who has the service open can call the service at 
anytime, even while someone else is in the middle of another call. Use semaphores to protect access 
where appropriate. 

You must also make sure that the a service's owning task will remain active for the real lifetime of the 
service. For instance, if a service is created via some transient user interface task such as a document or a 
tool, then the service instance will become invalid when that tool is shut down. 

An alternative to keeping the creating task around for the lifetime of the service instance is to use 
msgObjectNew to create the service instance under another task. A very good task to create instances 
under is the main task of the service. The service resource file handle is available for use with 
msgObjectNew. Use msgSvcGetCIassMetrics to get this handle (metrics. resFile), Send msgObjectNew 
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to this handle. Note that msgObjectNew must be sent, not called. Remember, any pointers in the 
msgObjectNew pArgs must be in global memory. 

Recovering From Unexpected Client Termination 

Service instances automatically detect if a client terminates unexpectedly; that is, if a client terminates 
while it is bound to the service instance or owns it. msgSvcClientDestroyedEarly is sent to the service 
instance when this condition is detected. Subclasses that maintain per-client state can handle this 
message and perform cleanup. By default the service is closed and unbound from the terminating object. 

Sample DLLMain Routine 

You must let the service framework know about a service by sending msgSvcClassInitService to your 
service class. Here's an example: 

STATUS EXPORTED DLLMain (void) 
{ 

SVC_INIT_SERVICE init Service; 

STATUS s; 

StsRet (ClsTestServicelnit () , s) ; 

inemset( init Service. spare, 0, sizeof(initService. spare) ) ; 

initService.autoCreate = true; 

initService.serviceType = 0; 

init Service. init ServiceFlags = 0; 

ObjCallRet (msgSvcClassInitService, clsTestService, SinitService, s) ; 

return stsOK; 

} // DllMain 

#ifndef SERVICE_INCLUDED 
#define SERVICE_INCLUDED 

#ifndef STREAM_INCLUDED 

#include <stream.h> 

#endif 

#ifndef FS_INCLUDED 

#include <fs.h> 

#endif 



Common #defines and typedefs 



Service Status Codes 

An exclusive-open service is already open by someone else (msgSvcOpenRequested), or a services target 
is already open (msgSvcOpenTarget). 

#define stsSvcAlreadyOpen MakeStatus (clsService, 1) 

A service tried to open its target but the target manager field is null. 

tdefine stsSvcNoTarget MakeStatus (clsService, 2) 

A service tried to open its target but the target service doesn't exist or the target's service manager hasn't 
shown up yet. 

tdefine stsSvcTargetNotBound MakeStatus (clsService, 3) 

An autoMsgPassing service tried to pass a message to its target, but the target was not open. 

tdefine stsSvcTargetNotOpen MakeStatus (clsService, 4) 



Target 
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An attempt was made to change ownership, queryLock, or deinstall an open service. 

#define stsSvcInUse MakeStatus (clsService, 5) 

Someone who wasn't the owner of a checkOwner service tried to open it. 

♦define stsSvcNotOwner MakeStatus (clsService, 6) 

Someone tried to open or queryLock a service that is queryLocked. 

♦define stsSvcLocked MakeStatus (clsService, 7) 

Problem following the target chain during msgSvcAutoDetectingHardware. 

♦define stsSvcValidConnectStyleNotFound MakeStatus (clsService, 8) 

A deinstallation is in process. No new clients can be accepted. 

♦define stsSvcDeinstalllnProcess MakeStatus (clsService, 10) 

A service of this name already exists and refuses to terminate. 

♦define stsSvcAlreadyExists MakeStatus (clsService, 11) 

A service was created with style.waitForTarget set to false and the target wasn't found at msgNew or 
msgSvcSetTarget time. 

♦define stsSvcTargetNotFound MakeStatus (clsService, 12) 



A target references another service. 

typedef struct SVC_TARGET { ^ 

OBJECT manager; B 

U8 pName [nameBuf Length ] ; ^ 

US spare [12]; 

} SVC TARGET, *P SVC TARGET; 



Service Class Metrics 



Passed back by msgSvcGetClassMetrics. Also used in clsServicelnstallMgr (servimgr.h) and 
cisServiceMgr (servmgr.h). 

typedef struct SVC_CLASS_METRICS { 

CLASS serviceClass; // The class of this service. 

US pClassName [nameBufLength] ; // Service class name. 

U32 type; // See svctypes.h. 

US pTypeName [nameBufLength] ; // Service type name. 

OS_PROG_HANDLE progHandle; // Service dll program handle. 

U32 initServiceFlags;// As specified in 

// msgSvcClassInitService. 

OBJECT resFile; // Handle to service res file. 

// Can be objNull if not 
// full environment and 
// service. res is empty. 

OBJECT serviceDir; // Dir handle to service global 

// directory. 

OBJECT privateServiceMgr; //Private service mgr, if the 

// svcCreatePrivateServiceMgr 
// flag is set. 

U32 reservedl; 

U32 reserved2; 

U32 reserved3; 

U32 reserved4; 

U32 reservedS; 

} SVC CLASS METRICS, *P SVC CLASS METRICS; 
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Auxiliary Messages 

See servmisc.h for less commonly used (but important!) service messages 



#ifndef SERVMISC_INCLUDED 
finclude <servniisc.h> 
#endif 



Creation Messages 



msgSvcClassInitService 

Initializes the service class. 

Takes P_SVC_INIT_SERVICE, returns STATUS. Category: class message. 
#define msgSvcClassInitService MakeMsg(clsService, 56) 

iTienfs You must send this message to the service class immediately after it has been created. 

initServiceFlags 

Don't show this service in the installer. User can't configure or deinstall the service if this flag is set 

#define svcNoShow ((U32) flagO) 

Automatically pop up the global service option card the first time this service is installed. 

#define svcPopupOptions ((U32) flagl) 

Don't copy in the state files from the INST directory when the service is installed. 

#define svcNoLoadlnstances ((U32) flag2) 

Create a private service manager for instances of this class. All instances of this class will automatically be 
added to the private service manager. See SVC_CLASS_METRICS for uid of the private service manager. 

#define svcCreatePrivateServiceMgr ((U32) flag3) 

Generate a complete process environment in the DLLMain() process. Right now this means creating 
theProcessResList. Also, a service resource file handle will be created even if the service resource file is 
empty. Note that a complete process environment takes up significant memory. Only turn this on if you 
need it. 

#define svcFullEnvironment ((U32) flag4) 

typedef struct SVC_INIT_SERVICE { 

BOOLEAN autoCreate; // Create an instance for each state 

// node at install and warm boot times. 
U32 serviceType; // Global service type. See 

// svctypes.h. Usually set to 0. 
U32 initServiceFlags; // Or-in InitService flags. 

U8 spare [12]; 

} SVC_INIT_SERVICE, *P_SVC_INIT_SERVICE; 

msgNew 

Creates a new service object. 

Takes P_SVC_NEW, returns STATUS. Category: class message. 

^ni€«ts Callers send msgNew to create a new service instance. The instance will add itself to one or more service 

managers. Clients should access the service instance via the service manager API after msgNew. 
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Superclass behavior includes associating the service with it's node in the filesystem, adding it to the 
specified service managers, and attempting to bind to a target service. If style.waitForTarget is false and 
the target isn't found then stsSvcTargetNotFound is returned. 

The following parameters are usually set by the caller of msgNew: 

♦ pServiceName 

♦ target 

The following parameters are usually set by the subclass of clsService in msgNewDefaults (after the 
ancestor call): 

♦ style (including openClass) 

♦ pManagerList 

♦ numManagers 

If a subclass wants to change the handleClass, fsNew, or fsNewExtra parameters it must also execute the 
following in its msgNewDefaults method, after sending msgNewDefaults to ancestor: 

pNew->svc. handleClass = myFSHandleClass; 

Ob jCallOK (msgNewDefaults, pNew->svc. handleClass, &(pNew->svc.fsNew) , s) ; 

Most services will not need to do this. 

If a service with the same name as the new service already exists on any relevant service manager, the old 
service will be destroyed and the new service will replace it. However, if any of the old services veto the 
termination then the new service will not be created and an error status (stsSvcAlreadyExists) is 
returned. S 

I 



styrn Vaiye stsNoMatch Target not found and style.waitForTarget is false. 

StsSvcAlreadyExists Service of this name already exists and can't be terminated. 
stsBadParam Illegal target type. 

r style.connectSfyle 

tdefine svcAutoDetect // Can auto-detect hardware connect/disconnect. 

#define svcNoAutoDetect 1 // Can't do hardware auto-detect. 

tdefine svcFollowTarget 2 // Connect state follows target's connect state. 

typedef struct SVC_STYLE { 

U16 waitForTarget : 1, // OK if target doesn't exist; wait for it 

// to show up. 

// Allow only one open or QueryLock at a time. 

// Reserved. 

// Set this service to be the owner of its 
// target when it receives 
// msgSvcChangeOwnerRequested. 

// Open/close our target when we are 
// opened/closed. 

// Forward all messages that are not 
// clsObject, clsService or clsOption 
// messages to target. 

// Only allow the owner to open us; 
// return stsNotOwner if opener is wrong. 

// Forward all option sheet messages to 
// target. If the target is exclusive open 
// and checkOwner, then only forward if 
// target is owned by this service instance. 

// Connect detect abilities. 

// Reserved. 



«A 



exclusiveOpen 

reservedl 

autoOwnTarget 


: 1, 
: 1, 
: 1, 


autoOpen 


: 1, 


autoMsgPass 


: 1, 


checkOwner 


: 1, 


autoOption 


: 1, 


connectStyle 
reserved2 


: 2, 
: 6; 
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CLASS openClass; 



U16 spare 1; 
U16 spare2; 
} SVC_STYLE, *P_SVC_STYLE; 

typedef struct SVC NEW ONLY { 



rgomenfs 



©mmems 



SVC_TARGET 


target; 


P_STRING 


pServiceName; 


SVC STYLE 


style; 


CLASS 


handleClass; 


FS_NEW 


fsNew; 


U32 


fsNewExtra[25] 


P_UID 


pManagerList; 


U16 


numManagers; 


U32 


unusedl ; 


U32 


unused2 ; 


U32 


unused3 ; 


U32 


unused4 ; 



// Class used to create object returned from 
// msgSMOpen. Can be objNull to return the 
// service instance object itself. 



// Initial target, target. manager 

// can be objNull for no target. 

// Name of instance. 

// Overall style. 

// Class of service's node handle. 

// NewArgs for handle, filled in 

// at msgNewDefault time. 

// Extra fsNew space. 

// List of service managers that 

// self should be added to. 

// Number of uids in manager list. 



} SVC_NEW_ONLY, *P_SVC_NEW_ONLY; 

fdefine serviceNewFields \ 
streamNewFields \ 
SVC_NEW_ONLY svc; 

typedef struct SVC_NEW { 

serviceNewFields 
} SVC_NEW, *P_SVC_NEW; 

msgNewDefaults 

Initializes the SVC_NEW structure to default values. 

Takes P_SVC_NEW, returns STATUS. Category: class message. 

typedef struct SVC_NEW { 

serviceNewFields 
} SVC_NEW, *P_SVC_NEW; 

Sets 

object.cap 1= objCapCall; // Client must not override this in msgjNiew 

svc. target, manager = objNull; 

strcpy(pNew->svc.target.pName, " "); 

svc.pServiceName = pNull; 

svc.style.waitForTarget = true; 

svc.style.exclusiveOpen = false; 

svc.style.autoOwnTarget = true; 

svc.style.autoOpen = false; 

svc.style.autoMsgPass = false; 

svc.style.checkOwner = false; 

svc.style.autoOption = false; 

svc. style, connects tyle = svcFollowTarget; 
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svc.style.openClass = objNull; 

svc.handleClass = clsFileHandle; 

ObjCallOK(msgNewDefaiilts, pNew->svc.handleClass, \&(svc.fsNew), s); 

svc.fsNew.fs.exist = fsExistOpen I fsNoExistCreate; 

svc.pManagerList = pNull; 

svc.numManagers = 0; 



State File Messages 



M 



msgSvcGetHandle 

Returns a handle to the service's state node. 

Takes P_OBJECT, returns STATUS. 

#define msgSvcGetHandle MakeMsg(clsService, 12) 

Every service instance has an open handle to its state node. Use this message when you want to update 
the contents of your state node. 

NOTE: This handle must NOT be freed, closed, or changed. 

msgSvcGetModified 

Gets the modified state of this service. ^^ 

^ . E 

Takes P_SVC_GET_SET_MODIFIED, returns STATUS. ^ 

#define msgSvcGetModified MakeMsg(clsService, 36) 

typedef struct SVC_GET_SET_MODIFIED { 

BOOLEAN modified; // modified state 

} SVC_GET_SET_MODIFIED, *P SVC GET SET MODIFIED; 

msgSvcSetModified 

Sets modified state of self 

Takes P_SVC_GET_SET_MODIFIED, returns STATUS. 

tdefine msgSvcSetModified MakeMsg(clsService, 20) 

^fesssge typedef struct SVC_GET_SET_MODIFIED { 

fergoments BOOLEAN modified; // modified state 

} S VC_GET_SET_MOD IF lED , *P_SVC_GET_SET_MOD IF lED ; 

Comments Service subclasses must send this message with pArgs->modified set to true whenever they change their 

state file. 

Propogates msglMModifiedChanged to everyone who has bound to this service and is an observer of all 
service managers that this service is on. 

See Also msglMModifiedChanged (instlmgr.h) 
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Target Messages 



msgSvcOpenTarget 

Attain access to the target service for data transfer. 

Takes P_SVC_OPEN_CLOSE_TARGET, returns STATUS. 

tdefine msgSvcOpenTarget MakeMsg(clsService, 13) 

Argomersfs typedef struct SVC_OPEN_CLOSE_TARGET { 

P_ARGS pArgs; // Open or close parameters. 

} SVC_OPEN_CLOSE_TARGET, *P_SVC_OPEN_CLOSE_TARGET; 

Backwards compatibility 

typedef SVC_OPEN_CLOSE_TARGET SVC_OPEN_TARGET, *P_SVC_OPEN_TARGET; 

Comments This call should be made when the service is ready to actually transfer data to its target. It will cause 

msgSMOpen to be sent to the target's service manager. The target service instance can refuse the 
subsequent msgSvcOpenRequested request if it wants. The target service should be kept open for the 
minimum time possible. 

This message is sent automatically if newArgs.style.autoOpen is true. Note that pArgs is set to pNull in 
this case. 

Sefiirn Value stsFailed target, type is not svcTypeService. 

stsSvcNoTarget target. manager is null. 

stsSvcNotBound service is still waiting to bind to its target. 

stsSvcAlreadyOpen target is already open. 

errors from msgSMOpen 

target service-specific errors 
See Also msgSMOpen (servmgr.h) 

msgSvcGloseTarget 

Give up data transfer access to the target service. 

Takes P_SVC_OPEN_CLOSE_TARGET, returns STATUS. 

#define msgSvcCloseTarget Mak;eMsg(clsService, 14) 

Messcsge typedef struct SVC_OPEN_CLOSE_TARGET { 

Argymeiits P_ARGS pArgs; // Open or close parameters. 

} SVC_OPEN_CLOSE_TARGET, *P_SVC_OPEN_CLOSE_TARGET ; 

Comments This will cause msgSMClose to be sent to the target's service manager, resulting in 

msgSVCCloseRequested being sent to the target. 

This message is sent automatically if newArgs.style.autoOpen is true. Note that pArgs is set to pNull in 
this case. 

iefyrn Voliie stsFailed target.type is not svcTypeService. 

See Also msgSMClose (servmgr.h) 
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ants 



msgSvcGetTarget 

Returns current target. 

Takes P_SVC_GET_TARGET, returns STATUS. 

tdefine msgSvcGetTarget MakeMsg(clsService, 15) 

typedef struct SVC_GET_TARGET { 

SVC_TARGET target; // Out: target 

OBJECT targetHandle; // Out: handle to target, if bound 

OBJECT targetService;// Out: target service, if open 

} SVC_GET_TARGET, *P_SVC_GET_TARGET; 

target contains the target that was specified at msgNew time or by the last msgSvcSetTarget. 

targetHandle contains the service manager handle onto our target if we have bound with the target, or 
objNull if we haven't yet bound. 

targetService is the actual service object if the target has been opened, objNull if it isn't open. 



msgSvcSetTarget 

Change our target. 

Takes P_SVC_SET_TARGET, returns STATUS. 

tdefine msgSvcSetTarget MakeMsg{clsService, 16) 

typedef struct SVC_SET_TARGET { 

SVC_TARGET target; 

} SVC SET TARGET, *P SVC SET TARGET; 



Closes the old target (if it is open), unbinds the old target (if it is bound) and attempts to bind with the ^ 

new target. style.waitForTarget specifies whether we will wait for the target to show up if it does not 

exist. 

Causes msgSvcTargetChanged to be sent. 

stsNoMatch new target doesn't exist and style.waitForTarget is false. 



Connection Messages 



msgSvcGetConnected 

Gets the connected state of this service. 

Takes P_SVC_GET_SET_CONNECTED, returns STATUS. 

tdefine msgSvcGetConnected MakeMsg(clsService, 19) 

Arguments typedef Struct SVC_GET_SET_CONNECTED { 

BOOLEAN connected; // connect state 

} SVC GET SET CONNECTED, *P SVC GET SET CONNECTED; 



msgSvcSetConnected 

Sets connection state of self 

Takes P_SVC_GET_SET_CONNECTED, returns STATUS. 

tdefine msgSvcSetConnected MakeMsg(clsService, 35) 
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Wessoge typedef struct SVC_GET_SET_CONNECTED { 

^rgiimenfs BOOLEAN connected; // connect state 

} SVC_GET_SET_CONNECTED, *P_SVC_GET_SET_CONNECTED; 

lomments This message should only be used by auto-detecting services that interface directly to hardware when 

they have determined that their connection state has changed. 

Propogates msgSMConnectedChanged to everyone who has bound to this service and is an observer of 
all service managers that this service is on. 

If a binding service's connectStyle is svcFoUowTarget, then it's connected state will mirror that of its 
target. This is will be the case for most services, and is how the connect state propogates up the target 
links. 

iee Also msgSMConncctedChanged (servmgr.h) 

Client Access Messages 

msgSvcBindRequested 

Client asked to bind to this service. 
Takes P_SVC_BIND, returns STATUS. 

#define msgSvcBindRequested 



typedef struct SVC_BIND { 

OBJECT caller; 

OBJECT manager; 



MakeMsg(clsService, 2) 



// Object making the request. 

// Service manager the request is 

// being made through. 



} SVC_BIND, *P_SVC_BIND; 

A client sent msgSMBind to a service manager. The service can refuse the request by returning stsFailed. 
The default superclass behavior is to return stsOK. 

The service manager maintains a list of all the objects that have bound to this service instance. The caller 
is added to this list if this message returns stsOK. This list is available via msgSvcGetBindList. 

Subclasses usually let ancestor handle this message. This message must always be passed to ancestor. 



msgSvcUnbindRequested 

Client asked to unbind from this service. 
Takes P_SVC_BIND, returns STATUS. 
#define msgSvcUnbindRequested 
typedef struct SVC_BIND { 



MakeMsg(clsService, 3) 



OBJECT 
OBJECT 



caller; 
manager; 



// Object making the request. 
// Service manager the request is 
// being made through. 
} SVC_BIND, *P_SVC_BIND; 

A client sent msgSMUnbind to a service manager or a client who was bound to the service was 
destroyed. 

The service cannot veto this request. The caller is removed from the service instance's bind list before 
this message is sent. 

Subclasses usually let ancestor handle this message. This message must be passed to ancestor. 
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msgSvcOpenRequested 

Client asked to open this service. 

Takes P_SVC_OPEN_CLOSE, returns STATUS. 

#define msgSvcOpenRequested MalceMsg(clsService, 4) 

Argyments typedef struct SVC_OPEN_CLOSE { 

OBJECT caller; // Object making the request. 

OBJECT manager; // Service manager the request is 

// being made through. 
P_ARGS pArgs; // Service-specific open or close 

// parameters. 
OBJECT service; // Out (msgSvcOpen) : In (msgSvcClose) : 

// uid of open handle or service. 
} SVC_OPEN_CLOSE, *P_SVC_OPEN_CLOSE ; 

Comments A client Sent msgSMOpen to a service manager. The service instance can refuse the open request by 

returning stsFailed. 

The service manager maintains a list of all the objects that have opened this service instance. The caller 
is added to this list if this message returns stsOK. This list is available via msgSvcGetOpenList. 

The service instance is marked in use when one or more clients have it open. A service that has instances 
that are in use cannot be deinstalled. 

If the style.exclusiveOpen is true then only one client can have the service open at a time. If 

style.checkOwner is true then the owner of the service is the only one that can open the service. Errors 

are returned to the client if these conditions aren't true; see servmgr.h for details. m 

Subclasses usually do some processing, then pass this message to superclass. This message must be passed ^ 

Ul 

to ancestor. <'> 

msgSvcOpenDefaultsRequested 

Client wants open pArgs initialized. 

Takes P_SVC_OPEN_CLOSE, returns STATUS. 

tdefine msgSvcOpenDefaultsRequested MakeMsg(clsService, 9) 

typedef struct SVC_OPEN_CLOSE { 

OBJECT caller; // Object making the request. 

OBJECT manager; // Service manager the request is 

// being made through. 
P_ARGS pArgs; // Service-specific open or close 

// parameters. 
OBJECT service; // Out (msgSvcOpen) : In (msgSvcClose) 

// uid of open handle or service. 
} SVC_OPEN_CLOSE, *P_SVC_OPEN_CLOSE; 

A client sent msgSMOpenDefaults to a service manager, 

msgSvcCloseRequested 

Client asked to close this service. 

Takes P_SVC_OPEN_CLOSE, returns STATUS. 

tdefine msgSvcCloseRequested MakeMsg{clsService, 5) 
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Message typedef struct SVC_OPEN_CLOSE { 

Arsoments OBJECT caller; // Object making the request. 

OBJECT manager; // Service manager the request is 

// being made through. 
P_ARGS pArgs; // Service-specific open or close 

// parameters. 
OBJECT service; // Out (msgSvcOpen) : In (msgSvcClose) : 

// uid of open handle or service. 
} SVC_OPEN_CLOSE, *P_SVC_OPEN_CLOSE ; 

Commerjfs A client has send msgSMClosed to a service manager or a client who had the service open was 

destroyed. The service cannot veto this request; it must perform any cleanup required at this time. The 
caller is removed from the open list before this message is sent. 

Subclasses usually do some processing, then pass this message to superclass. This message must be passed 
to ancestor. 



,onitfients 



msgSvcQueiyLockRequested 

Client asked to QueryLock this service. 

Takes pNull, returns STATUS. 

#define msgSvcQueryLockRequested MakeMsg(clsService, 6) 

A client has sent msgSMQueryLock to a service manager. QueryLocking a service lets the client get 
access to the service without opening it. However, if style.exclusiveOpen is true then the QueryLock 
counts as an open as far as allowing only one open at a time. 

Subclasses usually let ancestor handle this message. This message must be passed to ancestor. 



msgSvcQueryUnlockRequested 

Client asked to QueryUnlock this service. 
Takes pNull, returns STATUS. 

tdefine msgSvcQueryUnlockRequested MakeMsg(clsService, 7) 

:ooime«ts A client has sent msgSMQueryUnlock to a service manager. This releases a previous QueryLock. 

Subclasses usually let ancestor handle this message. This message must be passed to ancestor. 

msgSvcCharactersticsRequested 

Client asked to get characteristics of this service. 

Takes P_SVC_CHARACTERISTICS, returns STATUS. 

tdefine msgSvcCharacteristicsRequested MakeMsg(clsService, 54) 

^rgometits typedef struct SVC_CHARACTERISTICS { 

OBJECT handle; // Handle of item to get characteristics of. 

P_UNKNOWN pBuf; // Out through Ptr: Characterisitics buffer. 

U16 len; // In/Out: Buffer size. If then the 

// actual size is returned. 
} SVC CHARACTERISTICS, *P SVC CHARACTERISTICS; 



A client sent msgSMGetCharacteristics to a service manager. The service will return service-specific 
characteristics via pArgs->pBu£ pArgs->len specifies the maximum size of the client s buffer. If 
pArgs->len is then the service should return the actual size of its characteristics in pArgs->len and not 
pass back any data. 
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idefine tagServiceClassOptionSheet MakeTag(clsService, 1) 

tdefine tagServiceFirstTime MakeTag(clsService, 2) 

// Next message up: 59 
// Obsolete, here for backwards compatibility. 

fumfmn Prototype STATUS EXPORTED InitService ( 

P_STRING pReservedl, // Set this to pNull. 

CLASS serviceClass, // class id. 

BOOLEAN autoCreate, // Create an instance for each state 

// node at install and warm boot times, 

U32 serviceType, // Global service type. See 

// svctypes.h. Usually set to 0. 
U32 initServiceFlags, // Or-in InitService flags. 

U32 reserved2, // Set this to 

U32 reservedS) ; // Set this to 






ii(5-^-«:;S,:...: . 



SERVMGR.H 



This file contains the API definition for clsServiceMgr. 
clsServiceMgr inherits firom clsInstallMgr. 

Provides access to a category of PenPoint service instances. 



Introduction 



A service manager represents a category of services in PenPoint. Service managers have well-known ids so 
they can be globally accessed. PenPoint creates several service managers by default. They are: 

theModems Modems. 

thePrinters Printers. 

thePrinterDevices Devices that a printer can talk to. 

theSendableServices All services that interface to the Send Manager. See sendserv.h. 

thcTransportHandlers Transport level network protocol handlers. 

theLinkHandlers Link level network protocol stacks. 

theHWXEngines Installable handwriting engines. 

theMILDevices All MIL services (device drivers). 

theParallelDevices Parallel port devices. 

theSerialDevices Serial port devices. 

theHighSpeedPacketHandlers High performance packet drivers. 

theOutboxServices All outbox services. 

thelnboxServices All inbox services. 

theDatabases All PIA databases. 

Additional service managers can be created on the fly by third parties or by GO. 

All of the service instances in a given category are on that service manager. All the instances on a service 
manager support the same API, so they can be used interchangeably. 

Each service instance on a service manager is identified with a unique string name. For example, there 
might be three printers on thePrinters: "MyLaserJet", "MarketingPrinterl", and "LittleDotMatrix". 

You can find a particular service instance or enumerate all the instances that are available. You can 
observe a service manager and be informed when a new instance is added or an existing one goes away. 

Once you know which service instance you want to use you must open it in order to gain access. This 
returns the uid of the service. You can then send messages directly to the service object. You must close 
the service instance after you are done using it. 
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Basic Service Manager Usage 

The simplest use of a service manager is to access a known service instance on the manager. Here's an 
example: 

SM_ACCESS access; 
SM_RELEASE release; 

access. pServiceName = "Service Instance Name"; 
access. caller = self; 

ObjCallRet (msgSMAccess, aServiceManager, fiaccess, s) ; 
// access. service can now be sent messages. 

// When you are done with the service, release it. 

release. caller = self; 

release. service = access. service; 

release. handle = access. handle; 

ObjCallRet (msgSMRelease, aServiceManager, ^release, s) ; 

Some service instances allow the client to specify pArgs. You must initialize the pArgs with 
msgSMAccessDefaults for these. For example: 

access. pServiceName = "Service Instance Name"; 

access. caller = self; 

access. pArgs = &args; 

ObjCallRet (msgSMAccessDefaults, aServiceManager, &access, s) ; 

args . f oo = . . . ; 

ObjCallRet (msgSMAccess, aServiceManager, Saccess, s) ; 

Advanced Service Manager Usage 

Accessing a service instance is actually composed of several steps. msgSMAccess and msgSMRelease 
performs all of them at once; more sophisticated users might find situations where they need to control 
the intermediary steps themselves. 

Each service instance has a 32 bit "handle" associated with it in addition to its name. This handle is a 
convenient shorthand for referencing a service instance. Most service manager messages use handles. 
Note that a handle is not a permanent id; it is dynamically generated when a service instance is first 
added to a service manager, and regenerated whenever PenPoint is rebooted. Handles should never be 
filed. 

Enumerating all of the service instances on a service manager is done by getting a list of all the handles 
and going through the list. For example, here's some code that gets all the names of all the service 
instances on a manager list: 

OBJECT list; 

LIST_ENTRY le; 
IM_GET_SET_NAME getName; 

ObjectCall(msgIMGetList, aServiceManager, &list); 

ObjectCall(msgListNumItems, list, &n) ; 

for (le. position = 0; le. position < n; le.position++) { 

Ob jectCall (msgListGetltem, list, &le) ; 

getName. handle = (OBJECT) le.item; 

getName . pName = pName; 

ObjectCall(msgIMGetName, aServiceManager, SgetName) ; 

// le.item is the handle, pName contains the name. 
} 
ObjCallWarn(msgDestroy, list, pNull) ; 
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If you know the name of a service, you can get its handle with msglMFind: 

find.pName = "Service Instance Name"; 

Ob jectCall (msglMFind, aServiceManager, &find) ; 

service Inst anceHandle = find. handle; 

The next step in accessing a service instance is binding. Binding tells a service instance that you are 
interested in it. After you have bound to a service you will get messages from that service telling you 
about changes in its state, such as when it becomes connected or disconnected. 

bind. handle = servicelnstanceHandle; 

bind. caller = self; 

Ob jectCall (msgSMBind, aServiceManager, &bind) ; 

Next you become the owner of the service instance. Ownership gives you the right to open the instance. 
It is the mechanism used to ensure that only one client is using a exclusive access device (such as a serial 
port) at a time. Some services are non-exclusive access (such as network devices). Setting owner is a 
no-op for these. 

The owner protocol informs the both the new and old owners that an ownership change is being 
proposed. Either of them can veto the change. The service instance can also veto the change. 

The owner of a service can be set to objNulI to signify no owner. You should do this when you want to 
give up ownership of a service instance. 

Here is an example of requesting an owner change: 

setOwner . owner = newOwner; 

setOwner. handle = servicelnstanceHandle; 

Ob jectCall (msgSMSetOwner, aServiceManager, & setOwner ) ; }« 

u 

Now you can open the service. An open request can optionally take pArgs. The format of the pArgs is ^ 

service-specific. However, all the service instances on a particular service manager have the same pArgs •" 

format. The pArgs must be set to defaults with msgSMOpenDefaults. 

A service that has open instances cannot be deinstalled. An open service instance cannot have its owner 
changed. Here is an example of opening a service instance: 

open. caller = self; 

open. handle = servicelnstanceHandle; 

open.pArgs = &openArgs; 

Ob jectCall (msgSMOpenDefaults, aServiceManager, &open) ; 

Ob jectCall (msgSMOpen, aServiceManager, &open) ; 

// open. service contains the service object at this point 

Clients should close a service instance when they have completed using it: 

close. caller = self; 

close. handle = servicelnstanceHandle; 

close. service = open. service; 

close. pArgs = pNull; 

ObjectCall (msgSMClose, aServiceManager, &close) ; 

Clients should unbind from a service instance when they are no longer interested in it. 

unBind. handle = servicelnstanceHandle; 

unBind. caller = self; 

Ob jectCall (msgSMUnbind, aServiceManager, &unBind) ; 
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Additional Service Manager Functionality 

Adding yourself as an observer of a service manager will cause all notification messages from the service 
manager and all the service instances on the service manager to go to you. These messages include: 

msglMInstalled A new service has been added to the service manager. 

msglMDeinstalled A service has been removed from the service manager. 

msglMInUseChanged A service has been opened or closed. 

msglMModifiedChanged A service has modified its state node. 

msgSMConnectedChanged A service has become connected or disconnected. 

msgSMOwnerChanged The owner of a service has changed. 

Plus, any service instance can send service-specific notification messages via msgSvcPropagateMsg (see 
service.h). All observer messages include the handle of the service instance being affected and the uid of 
the service manager. 

Sometimes a client needs to access a service object without becoming the owner, or need to override the 
open checks. This can be done, but it must be done with care. msgSMQueryLock and msgSMQuery 
can be used to do this. 

QueryLocking a service returns the service uid without opening it. However, the call will fail if the 
service is exclusive-open and currently open. Also, a query lock will lock out other opens until the query 
lock is released. msgSMQueryUnlock must be sent to release the query lock. 

msgSMQuery is just like msgSMQueryLock, except no open check is made. 

Service managers automatically clean up if an object that owns or opens a service instance terminates 
before releaseing the service instance. 

There is a well-known list object, theServiceManagers, that is a list of all the service managers in the 
system. You can observe this list and get notification when a service manager is added and removed. 

Creating Nevsr Service Managers 

As stated above, PenPoint defines several default service managers. You can create additional service 
managers if you desire. 

PenPoint will automatically create a service manager if a service instance tries to add itself to a service 
manager and the service manager doesn't exist. This allows services to be arbitrarily installed and 
deinstalled without having to worry about who creates and frees the service manager. 

tifndef SERVMGR_INCLUDED 
♦define SERVMGR_INCLUDED 

tifndef SERVICE_INCLUDED 
finclude <service.h> 
#endif 

tifndef INSTLMGR_INCLUDED 
tinclude <instlmgr.h> 
tendif 
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msgNew 

Creates a new service manager. 

Takes P_SM_NEW, returns STATUS. Category: class message. 

Argyments typedef struct SM_NEW_ONLY { 

BOOLEAN autoDestroy; // Have the service manager be owned 

// by a system process, and have it 
// destroy itself when the number of 
// service instances on it goes to 0. 

BOOLEAN noChecks; // Turn off error checking, client 

// tracking and binding; a service 
//on this list cannot be a target. 
// This improves performance but 
// is dangerous. Experts only! 

U32 unused2; 

U32 unusedS; 

U32 unused4; 

} SM_NEW_ONLY, *P_SM_NEW_ONLY; 

#define serviceManagerNewFields \ 
installMgrNewFields \ 
SM_NEW_ONLY sm; 

typedef struct SM_NEW { 

serviceManagerNewFields 
} SM_NEW, *P_SM_NEW; 

Comments Clients (other than those who are creating their own service managers) do not call this message. The 



well-known service managers are created by the system at cold-boot time. 

msgNewDefaults 

Initializes the SM_NEW structure to default values. 

Takes P_SM_NEW, returns STATUS. Category: class message. 

Messoge typedef struct SM_NEW { 

Arguments serviceManagerNewFields 

} SM_NEW, *P_SM_NEW; 

Comments Sets 

InstallMgr.style.createlnitial = false; 
installMg^.style.copyOnlnstall = false; 
installMgr.style.addToGlobalList = false; 
installMgr.style.createlcon = false; 
sm.autoDestroy = false; 
sm. noChecks = false; 

msgDump 

Prints out the services known by this service manager and their state. 

Takes OBJ_KEY, returns STATUS. 

clsServiceManager provides an elaborate response to msgDump. This is very useful for debugging 
services! 



614 PENPOINT API REFERENCE 

Part 13 / Writing PenPoint Services 

msgSMAccess 

Accesses a service instance, given its name. 

Takes P_SM_ACCESS, returns STATUS. 

tdefine msgSMAccess MakeMsg(clsServiceMgr, 43) 

typedef struct SM_ACCESS { 

P_STRING pServiceName; // Service name. 

OBJECT caller; // Object making this call, 

// typically self. 

P_ARGS pArgs; // Use this if service requires pArgs. 

// Send msgSMAccessDefaults first. 

OBJECT handle; // Out: Service handle. 

OBJECT service; // Out: Service instance. 

} SM_ACCESS, *P_SM_ACCESS; 

Tliis is a convenience message tliat performs the sequence most clients do to access a service. 

This message performs a find, bind, setOwner, and open for the specified service. 

Note: This message cannot be used when you want to provide pArgs to a service. 

stsNoMatch Item not found. 

stsSvcLocked Someone has this exclusive-open service query locked. 

stsSvcNotOwner Someone else is the owner of this owner-checked service. 

stsSvcAlreadyOpen Someone already has this exclusive-open service open. 

Service-Specific Error Returns. 

msglMFind 



msgSMAccessDefaults 

Sets pArgs defaults for msgSMAccess. 

Takes P_SM_ACCESS, returns STATUS. 

tdefine msgSMAccessDefaults MakeMsg(clsServiceMgr, 45) 

Messege typedef struct SM_ACCESS { 

Arguments P_STRING pServiceName; // Service name. 

OBJECT caller; // Object making this call, 

// typically self. 
P_ARGS pArgs; // Use this if service requires pArgs. 

// Send msgSMAccessDefaults first. 
OBJECT handle; // Out: Service handle. 

OBJECT service; // Out: Service instance. 

} SM_ACCESS, *P_SM_ACCESS; 

Commeiits This message should be used if the service you wish to access takes pArgs. This message sets up the 

defaults for the pArgs. 

Ueium Value stsNoMatch Item not found. 

See Also msgSMAccess 
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Argymenfs 



Comments 



ietwrn Voiye 



See Also 



Argi««enfs 



Coitiments 



Refyrn Volye 



See Also 



msgSMRelease 



Releases a service instance. 

Takes P_SM_RELEASE, returns STATUS. 

#define msgSMRelease 

typedef struct SM_RELEASE { 

OBJECT caller; 

OBJECT handle; 

OBJECT service; 

} SM RELEASE, *P SM RELEASE; 



MakeMsg(clsServiceMgr, 44) 

// Object making this call, 
// typically self. 

// Service handle. 

// Service instance. 



Call this message when you are finished using a service. 

This is a convenience message that performs the sequence most clients do when they are finished with a 



service. 



This message performs a close, sets the owner to objNull, and unbinds. 
stsFailed Service is not open by the caller. 
Service-Specific Error Returns, 
msgSMClose 



msgSMBind 



Binds to a service. 

Takes P_SM_BIND, returns STATUS. 

♦define msgSMBind 

typedef struct SM_BIND { 

IM_HANDLE handle; 

OBJECT caller; 

} SM BIND, *P SM BIND; 



MakeMsg(clsServiceMgr, 1) 



// Service handle to bind to. 
// Object making this call. 



The caller is made an observer of this service. Service manager notification messages will be sent to the 
caller. 

The caller is added to the bind list of the service instance. 

Sends msgSvcBindRequested to the service being bound to. The service has the right to refiise the bind. 
The service-specific error return that indicates a refiisal is passed back to the client. 

stsBadObject Caller is not an object. 

stsBadAncestor Caller has invalid ancestor. 

Service-Specific Error Returns. 

msgSvcBindRequested (service, h) (service.h) 



msgSMUnbind 

Unbinds from a service. 

Takes P_SM_BIND, returns STATUS. 

♦define msgSMUnbind 



MakeMsg(clsServiceMgr, 2) 
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Me&sa^e typedef struct SM_BIND { 

Argymnents IM_HANDLE handle; // Service handle to bind to. 

OBJECT caller; // Object making this call. 

} SM_BIND, *P_SM_BIND; 

Comments This removes the caller as an observer of the handle and removes the caller from the service instance's 

bind list. 

Note: Clients must first close a service before unbinding from it. 

The service manager will automatically send msgSMUnbind for all services that are bound to a client 
when that client object is freed. This means that you must not send msgSMUnbind from your msgFree 
routine; the object freed notification occurs before your msgFree routine is entered. 

Sends msgSvcUnbindRequested to the service being unbound from. 

Return V0lwe stsFailed Service is not bound by the caller. 



msgSMGetOwner 

Gets the current owner of a service. 

Takes P_SM_GET_OWNER, returns STATUS. 

tdefine msgSMGetOwner MakeMsgiclsServiceMgr, 31) 

typedef struct SM_GET_OWNER { 

IM_HANDLE handle; // Handle of item to get owner on. 

OBJECT owner; // Out: current owner. 

} SM GET OWNER, *P SM GET OWNER; 



msgSMSetOwner 

Sets a new service owner. 

Takes P_SM_SET_OWNER, returns STATUS. 

Idefine msgSMSetOwner MakeMsg(clsServiceMgr, 11) 

Arguments typedef struct SM_SET_OWNER { 

IM_HANDLE handle; // Handle of item to set owner on. 
OBJECT owner; // New owner. 

} SM_SET_OWNER, *P_SM_SET_OWNER; 

CommeRfs Old and new owners (whether they are clients or other services) will recieve service messages which allow 

them to veto the ownership change and informs them that the change has taken effect. The message 
sequence is as follows: 

1 . msgSvcOwnerAquireRequested is sent to the new owner. The new owner can veto the owner 
change by returning a status of anything other than stsOK or stsNotUnderstood. msgSMSetOwner 
returns with the abort status, 

2. msgSvcOwnerReleaseRequested is sent to the old owner. The old owner can veto the owner change 
by returning a status of anything other than stsOK or stsNotUnderstood. If the old owner agrees to 
the ownership change it must immediately close the service if it is open. 

3. msgSvcChangeOwnerRequested is sent to the service. This informs the service that ownership is 
going to be changed and allows it to veto. By default the services will veto the change if they are 
open. 

4. msgSvcOwnerReleased is sent to the old owner. 

5. msgSvcOwnerAquired is sent to the new owner. 

6. msgSMOwnerChanged is sent to everyone who is bound to the service or observing a service 
manager that the service is on. 



Argymenfs 



lefyrsi ¥aii« 
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Return Voiue stsBadObjcct New owner is not an object. 

stsBadAncestor New owner has invalid ancestor. 

stsSvcInUse Service is open. 
See Also service.h, for definition of msgSvc... messages. 



msgSMOpen 

Opens a service, given its handle. 

Takes P_SM_OPEN_CLOSE, returns STATUS. 

tdefine msgSMOpen 



MakeMsg(clsServiceMgr, 4) 



typedef struct SM_OPEN_CLOSE { 
IM_HANDLE handle; 
OBJECT caller; 

P_ARGS pArgs ; 

OBJECT service; 



fee Also 



// Handle of service to open. 

// Object making this call. 

// Service-specific open parameters. 

// In: (SMClose) Out: (SMOpen) Service 
// object. 
} SM_OPEN_CLOSE, *P_SM_OPEN_CLOSE; 

Clients should do this only when they are ready to transfer data to the service, and should leave the 
service open for as little time as possible. 

A bind is automatically performed if the client is not yet bound. 

The caller is added to the open list of the service instance. 

Sends msgSvcOpenRequested to the service being opened. The service has the right to refuse the open. 
The service-specific error return that indicates a refusal is passed back to the client. 

stsBadObject Caller is not an object. 

StsBadAncestor Caller has invalid ancestor. 

stsSvcNotBound Caller is not bound to the service. 

stsSvcLocked Someone has this exclusive-open service query locked. 

stsSvcNotOwner Someone else is the owner of this owner-checked service. 

stsSvcAlreadyOpen Someone already has this exclusive-open service open. 

Service-Specific Error Returns 

msgSMBind (service.h) (service.h) (service.h) 



Messcsge 
Arquments 



msgSMOpenDefaults 

Initializes SMOpen pArgs to default value. 
Takes P_SM_OPEN_CLOSE, returns STATUS. 
tdefine msgSMOpenDefaults 



typedef struct SM_OPEN_CLOSE { 
IM_HANDLE handle; 

OBJECT caller; 

P_ARGS pArgs ; 

OBJECT service; 

} SM_OPEN_CLOSE, *P_SM_0PEN_CLOSE ; 
msgSMOpen (service.h) 



MakeMsg(clsServiceMgr, 34) 



// Handle of service to open. 

// Object making this call. 

// Service-specific open parameters. 

// In: (SMClose) Out: (SMOpen) Service 

// object. 
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msgSMClose 

Close an open service. 

Takes P_SM_OPEN_CLOSE, returns STATUS. 

fdefine msgSMClose MakeMsg(clsServiceMgr, 5) 

Message typedef struct SM_OPEN_CLOSE { 

ArgMmenfs IM_HANDLE handle; // Handle of service to open. 

OBJECT caller; // Object making this call. 

P_ARGS pArgs; // Service-specific open parameters. 

OBJECT service; // In: (SMClose) Out: (SMOpen) Service 

// object. 
} SM_OPEN_CLOSE, *P_SM_OPEN_CLOSE ; 

Comments The caller is removed from the open list of the service instance. 

Clients should send msgSMClose as soon as they are finished actively transfering data. Clients *must* 
first close a service before unbinding from it. 

The service manager will automatically send msgSMClose for all services that are held open by a client 
when that client object is freed. This means that you must not send msgSMClose from your msgFree 
routine; the object freed notification occurs before your msgFree routine is entered. 

Sends msgSvcCioseRequested to the service being opened. 

iettirn ¥oitie stsFailed Service instance is not open by the caller. 

msgSMQueryLock 

Gets the uid of a service and locks out any opens. 

Takes P_SM_QUERY_LOCK, returns STATUS. 

tdefine msgSMQueryLock MakeMsg(clsServiceMgr, 8) 

Argomefifs typedef struct SM_QUERY_LOCK { 

IM_HANDLE handle; // Handle of service instance to query. 

OBJECT service; // Out: Service object. 

} SM_QUERY_LOCK, *P_SM_QUERY_LOCK; 

Comments This message is similar to msgSMOpen, in that it returns a service object, given a handle. However, it is 

not seen as an open by the service. 

This message is meant for non-data transfer access to a service, for example, generating a service's option 
card. 

The sender of this message does *not* have to be the owner of the service. 

This message will fail if the service instance is exclusive open and currently in use (open). If this message 
succeeds then all opens will fail until msgSMQueryUnlock is sent. 

This message will return the real uid of the service instance in the case of a multi-user service. 

Return V'oloe stsSvcLocked Service instance is already query locked. 

stsSvcInUse Service instance is open. 
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msgSMQueryUnlock 

Unlocks a service that was locked via msgSMQueryLock. 

Takes P_SM_QUERY_UNLOCK, returns STATUS. 

♦define msgSMQueryUnlock MakeMsg(clsServiceMgr, 9) 

Argymenfs typedef struct SM_QUERY_UNLOCK { 

IM_HANDLE handle; // Handle of service instance to unlock, 

} SM QUERY UNLOCK, *P SM QUERY UNLOCK; 



Message 
Argument's 



Comments 



msgSMQuery 



Gets the uid of a service. 

Takes P_SM_QUERY_LOCK, returns STATUS. 

♦define msgSMQuery 



MakeMsg{clsServiceMgr, 33) 



typedef struct SM_QUERY_LOCK { 
IM_HANDLE handle; 
OBJECT service; 

} SM QUERY LOCK, *P SM QUERY LOCK; 



// Handle of service instance to query. 
// Out: Service object. 



This message gets the uid of a service instance. It must be used very carefully. It bypasses all checking 
mechanisms, so the caller can get into trouble if he subsequently sends messages to the service that are 
not expected. Use msgSMQueryLock instead of msgSMQuery if at all possible. 



msgSMGetCharacteristics 

Gets the characteristics of the specified service instance. 

Takes P_SM_GET_CHARACTERISTICS, returns STATUS. 

♦define msgSMGetCharacteristics MakeMsg(clsServiceMgr, 42) 

Arguments typedef Struct SM_GET_CHARACTERISTICS { 

IM_HANDLE handle; // Handle of item to get characteristics of. 

P_UNKNOWN pBuf; // Out through Ptr: Characterisitics buffer. 

U16 len; // In/Out: Buffer size. If then the 

// actual size is returned. 
} SM_GET_CHARACTERISTICS, *P_SM_GET_CHARACTERISTICS; 

Comments Characterstics are service-specific properties of a particular service. For example, modem services might 

pass back whether Fax is supported, maximum baud rate, etc. All the services on a particular service 
manager return the same characterstics set. 

Callers should first send this message with pArgs->len set to 0. This will return the size of the actual 
characterisitics buffer. Callers should then allocate this space and make the call again with pArgs->len set 
to this size. pArgs->len can be less than the actual size, in which case only the number of bytes specified 
by pArgs->len is returned. 



msgSMSave 

Saves a service instance to a specified external location. 

Takes P_SM_SAVE, returns STATUS. 

♦define msgSMSave MakeMsg(clsServiceMgr, 36) 



620 PENPOINT API REFERENCE 

Part 13 / Writing PenPoint Services 

gemenfs typedef struct SM_SAVE { 

IM_HANDLE handle; // Handle of service instance to save. 
BOOLEAN reserved; // Reserved. 

FS_FLAT_LOCATOR flat; // Location to save to. 
} SM_SAVE, *P_SM_SAVE; 

.mtnents The pArgs specify the parent directory that the service instance will save itself into. Note that the service 

instance's current target is also saved. When the service instance is reloaded it will try and bind to this 
target. 

e Also msgSvcClassLoadlnstance load a service instance from arbitrarylocation on disk (service.h). 



Auxiliary Messages 



msgSMFindHandle 

Finds a handle, given a service instance uid. 

Takes P_SM_FIND_HANDLE, returns STATUS. 

tdefine msgSMFindHandle MakeMsg(clsServiceMgr, 10) 

typedef struct SM_FIND_HANDLE { 

OBJECT service; // Service object to look for. 

IM_HANDLE handle; // Out: resulting handle. 

} SM_FIND_HANDLE, *P_SM_FIND_HANDLE; 

This message allows you to find the handle of a service if you know its uid. 
stsNoMatch Service not found on this service manager list. 



msgSMSetOwnerNoVeto 

Sets a new service owner without giving owners veto power. 

Takes P_SM_SET_OWNER, returns STATUS. 

tdefine msgSMSetOwnerNoVeto MakeMsg(clsServiceMgr, 30) 

Message typedef struct SM_SET_OWNER { 

Irgiiments IM_HANDLE handle; // Handle of item to set owner on. 

OBJECT owner; // New owner. 

} SM_SET_OWNER, *P_SM_SET_OWNER; 

:omni€Rts This message is the same as msgSMSetOwner, except the old owner and new owners do not get the 

chance to veto. msgSvcReleaseRequest and msgSvcAquireRequest are not sent. This message does the 
following: 

1 . The open status of the service is checked. If it is open (in use) the SetOwner fails, with a return 
status of stsSvcInUse. 

2. msgSvcChangeOwnerRequested is sent to the service. This informs the service that ownership is 
going to be changed and allows it to veto the owner change by returning anything other than stsOK 
or stsNotUnderstood. msgSMSetOwner returns with the abort status. 

3. msgSMOwnerChanged is sent to everyone who is bound to the service or observing a service 
manager that the service is on. 

4. msgSvcOwnerReleased is sent to the old owner. 

5. msgSvcOwnerAquired is sent to the new owner. 
lefyrn Vokm stsSvcInUse Service is open. 
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msgSMGetState 

Gets the state of a service. 

Takes P_SM_GET_STATE, returns STATUS. 

tdefine msgSMGetState MakeMsg(clsServiceMgr, 12) 

Argwments typedef struct SM_GET_STATE { 

IM_HANDLE handle; // In: Handle of service to get state on. 

BOOLEAN connected; // Out: Is service connected? 

OBJECT owner; // Out: My owner, if any. 

OBJECT owned; // Out: The service that I own, if any. 

U8 reserved [24]; 
} SM_GET_STATE, *P_SM_GET_STATE; 

Comments This message provides service state. There is some additional state (in use, modified) that is gotten via 

msglMGetState. See instlmgr.h for details. 



msgSMGetClassMetrics 

Gets the service's class metrics. 

Takes P_SM_GET_CLASS_METRICS, returns STATUS. 

tdefine msgSMGetClassMetrics MakeMsg(clsServiceMgr, 13) 

foients typedef struct SM_GET_CLASS_METRICS { 

IM_HANDLE handle; // Handle of item to get class metrics on. 

SVC_CLASS_METRICS metrics; 
} SM_GET_CLASS_METRICS, *P_SM_GET_CLASS_METRICS; 

u 
Bienfs This message passes back information about the service class. See service.h for a definition of ^ 

SVC_CLASS_METRICS. 

tnsglMDeinstall 

Remove and free a service instance. 

Takes P_IM_DEINSTALL, returns STATUS. 

ments This will remove the specified service instance from all the service managers that it is on, destroy its state 

file, and free it. 

Note that a service is initially created by sending msgNew to the service class. Services automatically add 
themselves to service manager. Do not use msglMInstall for this purpose; msglMInstall should 
NEVER be used by clients. 

Causes observer message msglMDeinstalled to be propogated to all objects that are bound to the service 
instance and to the service managers. 

This message causes msgSvcDeinstallRequested to be sent to the service instance. The instance can veto 
the deinstall at this point; if it does then the return value from msglMDeinstall is the status that the 
service instance used to veto the deinstall. 

ilso msgSvcDeinstallRequested 
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Notification Messages 

msgSMConnectedChanged 

A service s connection state changed. 

Takes P_SM_CONNECTED_NOTIFY, returns STATUS. Category: observer notification. 

#define msgSMConnectedChanged MakeMsg(clsServiceMgr, 20) 

typedef struct SM_CONNECTED_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HMDLE handle; // handle to service 

BOOLEAN connected; // new connect state 

} SM_CONNECTED_NOTIFY, *P_SM_CONNECTED_NOTIFY; 

msgSMOwnerChanged 

A service's owner has changed. 

Takes P_SM_OWNER_NOTIFY, returns STATUS. Category: observer notification. 

#define msgSMOwnerChanged MakeMsg(clsServiceMgr, 21) 

typedef struct SM_OWNER_NOTIFY { 

OBJECT manager; // manager that sent notification 

IM_HANDLE handle;. // handle to service 

OBJECT oldOwner; // old owner 

OBJECT owner; // new owner 

} SM OWNER NOTIFY, *P SM OWNER NOTIFY; 






;:;;::;;:;;,,,,P:i:iiii:?ii 








SERVMISC.H 



This file contains additional API definitions for clsService. 

clsService inherits from clsStream. 

Provides default behavior for services. 

This header file defines auxiliary clsService messages that are not used by the majority of service cHents. 

#ifndef SERVMISC_INCLUDED 
#define SERVMISC INCLUDED 



Owner Messages 



msgSvcGetMyOwner 

Gets the current owner of this service, if any. 

Takes P_OBJECT, returns STATUS. 

#define msgSvcGetMyOwner 

Passes back objNull if there is no current owner. 



MakeMsg (clsService, 21) 



msgSvcGetOwned 

Passes back the item that this service owns. 

Takes P_OBJECT, returns STATUS. 

#define msgSvcGetOwned MakeMsg (clsService, 31) 

This message is only valid for autoOwnTarget services (style. autoOwnTarget is true). 

If this service has become the owner of its target then this message passes back the item that it owns; 
otherwise it returns objNull. 



msgSvcOwnerReleaseRequested 

Is it OK to remove you as the owner of a service? 
Takes P_SVC_OWNED_NOTIFY, returns STATUS. 
tdefine msgSvcOwnerReleaseRequested 



MakeMsg (clsService, 38) 



typedef struct SVC_OWNED_NOTIFY { 

OBJECT ownedService; // The service or MIL conflict 

// group which will have its 
// owner changed. 
OBJECT oldOwner; // The old owner. 

OBJECT newOwner; // The proposed new owner. 

U8 reserved [1 6 ] ; 

} SVC_OWNED_NOTIFY, *P_SVC_OWNED_NOTIFY; 

A client sent msgSMSetOwner to a service manager for a service you currently own. See 
servmgr.h/msgSMSetOwner for details on the entire owner change message protocol. 
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You can veto the ownership change by returning anything other than stsOK or stsNotUnderstood. 

The service must not be in use for the owner change to occur. If you have the service open and want to 
give up ownership, you should close the service when you receive this message. 

This message must be passed to ancestor. 

msgSvcOwnerAcquireRequested 

Is it OK to make you the new owner of a service? 

Takes P_SVC_OWNED_NOTIFY, returns STATUS. 

tdefine msgSvcOwnerAcquireRequested MakeMsg{clsService, 39) 

sage typedef struct SVC_OWNED_NOTIFY { 

iitienfs OBJECT ownedService; // The service or MIL conflict 

// group which will have its 
// owner changed. 
OBJECT oldOwner; // The old owner. 

OBJECT newOwner; // The proposed new owner. 

U8 reserved [ 16 ] ; 

} SVC_OWNED_NOTIFY, *P_SVC_OWNED_NOTIFY; 

ments A client sent msgSMSetOwner to a service manager, proposing that you be the new owner of a service. 

See servmgr.h/msgSMSetOwner for details on the entire owner change message protocol. 

You can veto the ownership change by returning anything other than stsOK or stsNotUnderstood. 

This message must be passed to ancestor. 

msgSvcOwnerAcquired 

You are now the new owner of a service. 

Takes P_SVC_OWNED_NOTIFY, returns STATUS. 

#define msgSvcOwnerAcquired MakeMsg(clsService, 29) 

lage typedef struct SVC_OWNED_NOTIFY { 

msents OBJECT ownedService; // The service or MIL conflict 

// group which will have its 
// owner changed. 
OBJECT OldOwner; // The old owner. 

OBJECT newOwner; // The proposed new owner. 

U8 reserved [ 16] ; 

} SVC_OWNED_NOTIFY, *P_SVC_OWNED_NOTIFY; 

meiifs A client sent msgSMSetOwner to a service manager and requested that you become the new owner of 

the service. This message signifies that you are the new owner of the service. See 
servmgr.h/msgSMSetOwner for details on the entire owner change message protocol. 

Any saved state that you have for the owned service should be restored (typically via msgSvcSetMetrics). 

This message must be passed to ancestor. 



msgSvcOwnerReleased 

You are no longer the owner of a service. 

Takes P_SVC_OWNED_NOTIFY, returns STATUS. 

tdefine msgSvcOwnerReleased MakeMsg(clsService, 30) 
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lessage typedef struct SVC_OWNED_NOTIFY { 

arguments OBJECT ownedService; // The service or MIL conflict 

// group which will have its 
// owner changed. 
OBJECT oldOwner; // The old owner. 

OBJECT newOwner; // The proposed new owner. 

U8 reserved [ 16 ] ; 

} SVC_OWNED_NOTIFY, *P_SVC_OWNED_NOTIFY; 

ommenfs A client Sent msgSMSetOwner to a service manager for a service you currently own. This message 

signifies that you are no longer the ow^ner of the service. See servmgr.h/msgSMSetOwner for details on 
the entire ow^ner change The ownership change actually happens when you return from this message. 

Any state for the owned state that you are interested in preserving should be gotten (typically via 
msgSvcGetMetrics) and saved in your state file. You can manipulate the service as its owner until you 
return from this message. 

This message must be passed to ancestor. 

msgSvcChangeOwnerRequested 

Owner change request message. 

Takes P_SVC_OWNED_NOTlFY, returns STATUS. 

tdefine msgSvcChangeOwnerRequested MakeMsg(clsService, 40) 

lessage typedef struct SVC_OWNED_NOTIFY { 

.rgymsiits OBJECT OwnedService; // The service or MIL conflict 

// group which will have its 

// owner changed. y 

OBJECT oldOwner; // The old owner. ^ 

OBJECT newOwner; // The proposed new owner. 

U8 reserved [16]; 

} SVC_OWNED_NOTIFY, *P_SVC_OWNED_NOTIFY; 

omttierifs This message is sent to the service instance whose owner is being changed. The service instance can veto 

the ownership change by returning anything other than stsOK or stsNotUnderstood. 

This message must be passed to ancestor if the service does not want to veto the owner change. 



Save Messages 



msgSvcSaveRequested 

Client asked to save this instance to external media. 

Takes P_FS_FLAT_LOCATOR, returns STATUS. 

tdefine msgSvcSaveRequested MakeMsg(clsService, 34) 

Coitimenfs A client Sent msgSMSave to a service manager. 

Default superclass behavior is to save the state file and the current target onj^. Subclasses should ensure 
that their state file is up to date if they wish to make use of this behavior. Alternatively, subclasses can 
not pass this message to ancestor and perform whatever form of save they wish. 

The pArgs references the parent directory in which this service instance should be saved. If a node with 
the same name as the service instance already exists within this directory, default superclass behavior is to 
overwrite the destination. Subclasses can perform other forms of behavior if the destination exists before 
passing this message to ancestor. 

This message does not have to be passed to ancestor. 
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msgSvcClassLoadlnstance 

Loads an instance state file firom disk and creates a new instance. 

Takes P_SVC_LOAD_INSTANCE, returns STATUS. Category: class message. 

♦define msgSvcClassLoadlnstance MakeMsg(clsService, 47) 

Argymenfs typedef Struct SVC_LOAD_INSTANCE { 

FS_LOCATOR source; // Source state file location. • 

} SVC_LOAD_INSTMCE, *P_SVC_LOAD_INSTANCE; 

Comments This flinction copies the state node specified by pArgs->source into the INST directory of the service 

and starts up an instance of the service on this state file. This is very similar to what happens when a 
warm-boot occurs, or when state nodes are automatically loaded when a service is first installed. 

If a service instance with the same name already exists, default behavior is to generate a unique name for 
the new service instance. 

Subclasses do not normally process this message, but can if they wish to change the exist behavior. 

Setiirn Value stsFSNodeNotFound source file not found. 

See Also msgSMSave 



Class Metrics Messages 



msgSvcGetClassMetrics 

Gets metrics for the service class that controls this instance. 

Takes P_SVC_CLASS_METRICS, returns STATUS. 

♦define msgSvcGetClassMetrics MalceMsg(clsService, 23) 

Note: This message can also be sent directly to the service class. 



Instance Metrics Messages 



msgSvcGetMetrics 

Passes back the current configuration metrics. 

Takes P_SVC_GET_SET_METRICS, returns STATUS. 

♦define msgSvcGetMetrics MakeMsg{clsService, 32) 

iim&nU typedef struct SVC_GET_SET_METRICS { 

P_UNKNOWN pMetrics; // Out through Ptr: Metrics buffer. 

U16 len; // In/Out: Metrics buffer size in 

// bytes. If then the actual 
// size is returned. 
} SVC_GET_SET_METRICS, *P_SVC_GET_SET_METRICS; 

imefits Configuration metrics are service specific. This interface allows the caller to find out how large the 

metrics set for a given service are. 

The caller should first send msgSvcGetMetrics with pArgs->len set to to get the actual size of the 
metrics buffer. The caller should allocate a buffer of this size then send the message again. 

Subclasses that have configuration metrics must handle this message. 
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msgSvcSetMetrics 

Sets the configuration metrics. 

Takes P_SVC_GET_SET_METRICS, returns STATUS. 

♦define msgSvcSetMetrics MakeMsg(clsService, 33) 

Messoge typedef struct SVC_GET_SET_METRICS { 

Arguments P_UNKNOWN pMetrics; // Out through Ptr: Metrics buffer. 

U16 len; // In/Out: Metrics buffer size in 

// bytes. If then the actual 
// size is returned. 
} SVC_GET_SET_METRICS, *P_SVC_GET_SET_METRICS; 

Comments Configuration metrics are service specific. The caller should set pArgs->len to the size that was returned 

from msgSvcGetMetrics when the metrics were originally gotten. A caller should never try and 
synthesize a metrics bufi^er; he should only pass back a buffer that was gottem from msgSvcGetMetrics. 

Subclasses can determine the version of a configuration buffer from its size. Subclasses should make sure 
that different versions of configuration information have different sizes. 

Subclasses must update their state node when they handle this message. 

Subclasses that have configuration metrics must handle this message. 



Service Manager Messages 



msgSvcAddToManager 

Add this service instance to a service manager. 

Takes P_SVC_ADD_TO_MANAGER, returns STATUS. p» 

tdefine msgSvcAddToManager MakeMsg(clsService, 17) 

typedef struct SVC_ADD_TO_MANAGER { 
OBJECT manager; 

} SVC_ADD_TO_MANAGER, *P_SVC_ADD_TO_MANAGER; 

This message allows a service to add itself to additional service managers after msgNew time. 
This results in msglMInstalled being sent to observers of the service manager. 

msgSvcRemoveFromManager 

Removes this service instance from a service manager. 

Takes P_SVC_REMOVE_FROM_MANAGER, returns STATUS. 

#define msgSvcRemoveFromManager MakeMsg( els Service, 18) 

typedef struct SVC_REMOVE_FROM_MANAGER { 

OBJECT manager; // Manager to remove self from 

} SVC_REMOVE_FROM_MANAGER, *P_SVC_REMOVE_FROM_MANAGER; 

This message allows a service to remove itself from a service manager it is currently on. 

This results in msglMDeinstalled being sent to observers of the service manager and any objects which 
have bound to this service. It cleans up this service's bind list, removing anyone who bound via the 
specified service manager. 

Note: service managers automatically remove a service when the service class is deinstalled. There is no 
need to do so explicitly. 

stsNoMatch Service instance is not on the specified service manager. 
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Client List Messages 

msgSvcGetBindList 

Gets a list of all the callers that have bound to this service. 

Takes P_SVC_GET_LIST, returns STATUS. 

#define msgSvcGetBindList •MakeMsg(clsService, 26) 

typedef struct SVC_GET_LIST { 

P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC GET list, *P SVC GET LIST; 



msgSvcGetOpenList 

Gets a list of all the callers that have opened this service. 

Takes P_SVC_GET_LIST, returns STATUS. 

♦define msgSvcGetOpenList MakeMsg(clsService, 27) 

Message typedef Struct SVC_GET_LIST { 

ArgiisTients P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC_GET_LIST, *P_SVC_GET_LIST; 

s o ™ : < msgSvcGetOpenObjectList 

msgSvcGetOpenObjectList 

Gets a list of the open objects which were returned for each open. 

Takes P_SVC_GET_LIST, returns STATUS. 

tdefine msgSvcGetOpenObjectList MakeMsg(clsService, 49) 

Message typedef struct SVC_GET_LIST { 

Arguments P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC_GET_LIST, *P_SVC_GET_LIST; 

Commems This Ust is ordered the same as the open list. The caller in openlist[i] was given the object in 

openObjectList[i] . 

« . msgSvcGetOpenList 



msgSvcGetManagerList 

Gets a list of all the service managers that this service is on. 

Takes P_SVC_GET_LIST, returns STATUS. 

fdefine msgSvcGetManagerList MakeMsg(clsService, 28) 
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lessage typedef Struct SVC_GET_LIST { 

ifgymersts P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC_GET_LIST, *P_SVC_GET_LIST; 

ee Also msgSvcGetManagerHandlcList 

msgSvcGetManagerHandleList 

Gets a list of the svc mgr handles that this service is represented by. 

Takes P_SVC_GET_LIST, returns STATUS. 

tdefine msgSvcGetManagerHandleList MakeMsg(clsService, 50) 

tesscige typedef struct SVC_GET_LIST { 

.rgwmefifs P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC_GET_LIST, *P_SVC_GET_LIST; 

omments This list is Ordered the same as the manager list. The handle in handleList[i] is this service's handle in 

serviceManagerList[i] . 

ee Also msgSvcGetManagerList 

msgSvcGetDependentAppList 

Gets a list of thelnstalledApps handles for all dependent apps. > 

Takes P_SVC_GET_LIST, returns STATUS. 

tdefine msgSvcGetDependentAppList MakeMsg{clsService, 51) 

tes5«§e typedef struct SVC_GET_LIST { 

krgymenfs P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC_GET_LIST, *P_SVC_GET_LIST; 

msgSvcGetDependentServiceList 

Gets a list of thelnstalledServices handles for all dependent services. 

Takes P_SVC_GET_LIST, returns STATUS. 

tdefine msgSvcGetDependentServiceList MakeMsg(clsService, 52) 

tesssge typedef struct SVC_GET_LIST { 

irgumeiits P_OBJECT pList; // Out: list, allocated from process heap. 

// CLIENT MUST OSHeapBlockFree WHEN 
// FINISHED! 
U16 count; // Out: number of elements in list 

} SVC GET LIST, *P SVC GET LIST; 
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Deinstallation/Destruction Messages 



msgSvcClassTerminateOK 

Deinstalls the entire service. 

Takes P_OBJECT, returns STATUS. Category: class message. 

Idefine msgSvcClassTerminateOK MakeMsg(clsService, 43) 

Comments Deinstallation is a two-phase process. The first phase allows any of the services or apps being deinstalled 

to cancel the entire deinstall. msgSvcClassTerminateOK is the veto phase. Returning anything other 
than stsOK signifies a veto. If anyone vetos the deinstall then msgSvcCiassTerminate Vetoed is sent to 
all services that were sent msgSvcClassTerminateOK. If nobody vetos the deinstall then 
msgSvcCiassTerminate is sent. 

The pArgs to msgSvcClassTerminateOK is used to pass back the object which is responsible for the 
veto. 

Default superclass behavior is to send msgSvcDeinstallRequested to each instance of the service, and 
veto the deinstallation if any service instance vetos the deinstallation. The uid of the instance that vetoed 
the deinstall is passed back via the pArgs. 

This approach allows multiple services and applications that are dependent on each other to be 
deinstalled in a coherent fashion. 



Subclasses can override this message if they wish. 
msgSvcDeinstall 



msgSvcClassTerminateVetoed 

Deinstall process was vetoed. 

Takes P_SVC_TERMINATE_VETOED, returns STATUS. Category: class message. 

#define msgSvcClassTerminateVetoed MakeMsg(clsService, 45) 

typedef struct SVC_TERMINATE_VETOED { 

OBJECT vetoer; // Object that vetoed the deinstall. 

STATUS status; // Veto status. 

} SVC_TERMINATE_VETOED, *P_SVC_TERMINATE_VETOED ; 

This message informs the service that the deinstallation sequence that started with 
msgSvcClassTerminateOK has been vetoed by one of the services or applications that was part of the 
deinstall. 

pArgs->vetoer gives the uid of the object or class which vetoed the deinstall. pArgs->status gives the 
return status of the veto. 

Default superclass behavior is to send msgSvcDeinstallVetoed to each instance of the service. 

Subclasses can override this message if they wish. 

msgSvcDeinstallVetoed 



msgSvcCiassTerminate 

Terminate the service. 

Takes pNuII, returns STATUS. Category: class message. 

♦define msgSvcCiassTerminate MakeMsg(clsService, 24) 
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CommenH Unconditionally terminate the service. All applications and services that are to be deinstalled have agreed 

to the deinstallation. 

Default superclass behavior is to send msgDestroy to each instance of the service. 

Subclasses must pass this message to ancestor. 

See Also msgDestroy 



msgSvcClientDestroyedEarly 

An active client was destroyed. 

Takes OBJECT, returns STATUS. 

tdefine msgSvcClientDestroyedEarly MakeMsg(clsService, 48) 

This message is sent to the service instance when a caller or service owner terminates unexpectedly. The 
pArgs is the uid of the caller or owner. 

Superclass behavior is to clean up the service instance by sending msgSMUnbind, msgSMClose and 
msgSMSetOwner to self as appropriate. 

Services that keep their own per-client information will need to process this message in order to clean up 
their state. 

This message must be passed to ancestor. 



msgSvcDeinstallRequested 

Client asked to destroy this service instance. 

Takes pNuU, returns STATUS. 

tdefine msgSvcDeinstallRequested MakeMsg{clsService, 8) 

Comments A client has sent msgSMDeinstall to a service manager (to get rid of just this service instance), or the 

entire service class is being deinstalled. 

Deinstallation is a two phase process. All service instances that are going to be deinstalled are sent 
msgSvcDeinstallRequested. Each service has the chance to veto the deinstall by returning an error 
status. If all parties agree to the deinstall then msgFree is sent to each service instance. msgFree cannot 
be vetoed. It causes the service to be removed from all service managers. 

If anybody vetos the deinstall then msgSvcDeinstallVetoed is sent to each service that is part of the 
deinstall process. Services should not accept any new clients while a deinstall is in process. 
msgSvcDeinstallVetoed indicates that new clients can once again be accepted. 

Default superclass behavior is to veto the deinstall if the service is in use (open). The superclass will also 
handle new client rejection while a deinstall is in process if it gets this message. 

This message must be passed to ancestor. 

Note: A service might get msgSvcDeinstallRequested more than once for a given deinstallation 
sequence. 

msgSvcDeinstallVetoed 

Deinstallation process was vetoed. 

Takes P_SVC_DEINSTALL_VETOED, returns STATUS. 

tdefine msgSvcDeinstallVetoed MakeMsg{clsService, 47) 
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krguments typedef Struct SVC_DEINSTALL_VETOED { 

OBJECT vetoer; // Object that vetoed the deinstall, 

STATUS status; // Veto status. 

} SVC_DEINSTALL_VETOED, *P_SVC_DEINSTALL_VETOED; 

;oRinients One of the objects or classes in the deinstall process decided to veto the deinstall. 

Services can once again accept new clients. 
This message must be passed to ancestor. 



msgDestroy 

Frees a service instance. 

Takes OBJ_KEY, returns STATUS. 

Subclasses should destroy all dynamic resources. Warning: Do not destroy any clsService resources, such 
as the state node handle! 

WARNING: Clients must NEVER send msgDestroy directly to a service instance; instead they should 
send msglMDeinstall to a service manager which the service instance is on. 

Note that service manager message msgSMRemoveReference allows a service instance to be removed 
from a single service manager without removing it from other service managers, or destroying the 
instance. See servmgr.h for details on msglMDeinstall and msgSMRemoveReference. 



Miscellenous Messages 



msgSvcGetStyle 

Returns current style settings. 

Takes P_SVC_STYLE, returns STATUS. 

fdefine msgSvcGetStyle MakeMsg (clsService, 10) 



msgSvcSetStyle 

Changes style settings. 

Takes P_SVC_STYLE, returns STATUS. 

#define msgSvcSet Style MakeMsg (clsService, 11) 

msgSvcGetFunctions 

Passes back a pointer to a table of function entry points. 

Takes P_SVC_GET_FUNCTIONS, returns STATUS. 

#define msgSvcGetFunctions MakeMsg (clsService, 1) 

Argometifs typedef Struct SVC_GET_FUNCTIONS { 

P_UNKNOWN pFunctions; // Out: Pointer to function table. 

U32 info; // Out: service-specific info. 

} SVC_GET_FUNCTIONS, *P_SVC_GET_FUNCTIONS; 

Comrnents This is for services that cannot afford the overhead of being accessed via object calls. The format of this 

pointer block is up to the subclass. Default superclass behavior is to set pFunctions to pNull, which 
means this service doesn't provide a table. 

Subclasses should handle this message if they wish to provide a function interface to their service. 

Default superclass behavior is to set pArgs->pFunctions to pNull and pArgs->info to 0. 
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msgSvcGetName 

Gets the name of this service instance. 

Takes P_SVC_GET_NAME, returns STATUS. 

♦define msgSvcGetName MakeMsg(clsService, 22) 

typedef struct SVC_GET_NAME { 

P_STRING pName; // Out: caller must allocate 

// nameBuf Length buffer here 
} SVC_GET_NAME, *P_SVC_GET_NAME; 

msgSvcNameChanged 

The service's name has been changed. 

Takes pNuU, returns STATUS. 

tdefine msgSvcNameChanged MakeMsg(clsService, 55) 

This message is self-sent to the service instance when its name is changed. This occurs when 
msglMSetName is sent to a service manager that this service is on. 

The service is already set to the new name when this message is recieved. msgSvcGetName can be used 
to get the new name. 

This message is informational only. It does not have to be passed to ancestor. 

msgSvcPropagateMsg ^ 

Propagates a service-specific message. ^ 

Takes P_SVC_PROPAGATE_MSG, returns STATUS. « 

tdefine msgSvcPropagateMsg MakeMsg(clsService, 25) 

typedef struct SVC_PROPAGATE_MSG { 
P_ARGS pArgs ; 

SIZEOF pArgsSize; 

MESSAGE msg; 

} SVC_PROPAGATE_MSG, *P_SVC_PROPAGATE_MSG; 

This message allows services to send their own informational messages to everyone who is bound to the 
service and everyone who is an observer of any service manager that this service is on. This is similar to 
what the system does with messages like msgSMConnectedChanged. 

The first two arguments of the pArgs of your notification message must be: 

OBJECT manager; // manager that sent notification_HANDLE handle; // handle to 

service 

msgSvcPropagateNotify will fill these in with the correct service manager and handle for all of the 
observers. For example: 

typedef struct FOO_NOTIFY { 

OBJECT manager; // svc manager that sent notification. 

OBJECT handle; // handle to service. 

FOO newFoo; // new foo. 

FOO oldFoo; // old foo. 

} FOO_NOTIFY, *P_FOO_NOTIFY; 

FOO_NOTIFY fooNotify; SVC_PROPAGATE_MSG propagate; 

propagate. pArgs = fooNotify; propagate. pArgsSize = SizeOf (fooNotify) ; propagate. msg = msgFoo; 

Ob jCallRet (msgSvcPropagateMsg, self, &propagate, s); 
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msgSvcAutoDetectingHardware 

Is the hardware that this service ultimately talks to auto-detecting? 

Takes P_BOOLEAN, returns STATUS. 

#define msgSvcAutoDetectingHardware MakeMsg(clsService, 37) 

This message is propogated to this service's target, then the target's target, etc. until it finds the service 
which actually interfaces to hardware (has no target). The hardware interface service is then asked if it 
can autodetect connect/disconnect. 

stsSvcValidConnectStyleNotFound target chain ended without reaching hardware service instance. 



msgSvcClassPopUpOptionSheet 

Creates an option sheet for the service's global options and pops it up. 
Takes pNull, returns STATUS. Category: class message. 

#define msgSvcClassPopUpOptionSheet MakeMsg(clsService, 57) 

merits The Option sheet is only displayed if this is the first time the service is installed. 

Subclasses do not normally process this message. 

msgSvcClassGetlnstallDir 

Creates a directory handle on the service's installation directory. 

Takes P_OBJECT, returns STATUS. 

#define msgSvcClassGetlnstallDir MakeMsg(clsService, 58) 

The service class creates a clsDirHandle object which references the location on external media that the 
service was installed from. If the external volume is not connected, the user is asked to attach it. 

If this service was bundled with PenPoint then there is no valid external volume beyond installation 
time. stsFailed is returned in this case. 

NOTE: CALLER IS RESPONSIBLE FOR DESTROYING THE DIR HANDLE WHEN DONE. 

rn Voiye stsOK The external volume is attached. The user tapped the Cancel button when promptedto attach 

the external volume. The external volume cannot be determined becausethis application was 
bundled with PenPoint. 

Descendants: You normally do not handle this message. 

Notification Messages 



msgSvcTargetChanged 

A service's target has changed. 

Takes P_SVC_TARGET_CHANGE_NOTIFY, returns STATUS. Category: observer notification. 

#define msgSvcTargetChanged MakeMsg(clsService, 53) 

typedef struct SVC_TARGET_CHANGE_NOTIFY { 

OBJECT manager; // svc manager that sent notification. 

OBJECT handle; // handle to service. 

SVC_TARGET oldTarget; // old target. 

SVC_TARGET newTarget; // new target. 

} SVC_TARGET_CHANGE_NOTIFY, *P_SVC_TARGET_CHANGE_NOTIFY; 

This message is broadcast to all service managers that this service is on. 
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SVCTYPES.H 



This file contains the type tags for services. These tags are used to provide categories of service classes. 
This allows UIs like the printer manager UI to decide what types are available. 



#ifndef SVCTYPES_INCLUDED 

♦define SVCTYPES_INCLUDED 

tifndef GO_INCLUDED 

# include <go.h> 

tendif 

♦define svcTypePrinter 

♦define svcTypeEMail 



MakeTag(clsService, 1) 
MakeTag(clsService, 2) 
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BATTERY.H 



This file contains the API definition for clsMILPowerDevice. 

clsMILPowerDevice inherits from clsSemce. 

theBattery is a well-known instance of clsMILPowerDevice. theBattery provides access to the primary 
battery of the computer. 

theBatteries is a well-known instance of clsServiceManager. theBatteries is the service manager that 
manages the instances of clsMILPowerDevice that represent the computer's batteries (including 
theBattery). 

clsMILPowerDevice provides an object interface to the computer's power devices (i.e. batteries). 

#ifndef BATTERY_INCLUDED 
#define BATTERY_INCLUDED 

#ifndef MILSERV_INCLUDED 
tinclude <milserv.h> 
#endif 



Types and Constants 



// battery flags 
#define milRawVoltsSupported 
tdefine milPercentLeftSupported 
#define milSecondsLeftSupported 
#define itiilSetLevelSupported 



flagO 
flagl 
flag2 
flags 



Messages 



msgBatteiyGetMetrics 

Passes back the battery's metrics. 

Takes P_BATTERY_METRICS, returns STATUS. 

#define msgBatteryGetMetrics 

typedef struct BATTERY_METRICS { 

U16 batteryFlags; 

U16 maxMillivolts; 

U16 warnMillivolts; 

U16 failMillivolts; 

U16 currentMillivolts; 

U16 percentOfBatteryLeft; 

U16 maxSeconds ; 

U16 secondsOfBatteryLeft; 
} BATTERY METRICS, * P BATTERY METRICS; 



MakeMsg (clsMILPowerDevice, 1) 



// flags defined above 
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msgBatteiySetLevel 

Sets the percentage of battery remaining. 

Takes U16, returns STATUS. 

tdefine msgBatterySetLevel MakeMsg(clsMILPowerDevice, 2) 

The MIL request milPowerSetBatteryLevel is sent to the MIL device unit represented by the receiver. 

msgBatteiyLow 

Sent when a battery level is dangerously low. 

Takes void, returns STATUS. Category: observer notification. 

Idefine msgBatteryLow MakeMsg(clsMILPowerDevice, 128) 

msgBatteiyCritical 

Sent when a battery drops level below the shutdown level. 
Takes void, returns STATUS. Category: observer notification. 

#define msgBatteryCritical MakeMsg(clsMILPowerDevice, 129) 
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DYNARRAY.H 



This file contains the API definition for dynarray. Dynarrays provide a set of dynamic array routines. 

The fiinctions described in this file are contained in XLIST.LIB. 

Implements a dynamic array of elements. Standard interface routines for indexing, inserting, deleting, 
and other common operations are provided. This interface is primarily used internally to GO, and is 
therefore tailored to meet internal needs. 

A dynamic array is a simple data structure that contains some array information fields, and a pointer to a 
block of memory. This block of memory is equal to pArray->entries * pArray->elementSize. 

The number of entries is specified at initialization time in DynArrayNew, and can be changed via 
DynArrayContract, or DynArrayExpand. These are implicitly called from DynArraylnsert and 
DynArrayDelete when inserting an item into a list that does not have enough entries available, or when 
deleting an item from the list. At any time, the value returned by DynArrayCount, or pArray->entries, 
will be equal to the number of entries allocated in the array in pArray->pData. The size of the array in 
pArray->pData will be equal to pArray->entries * pArray->elementSize. 

The maximum index set in the array at any given time, independent of the number of entries in the 
array, is referred to as maxCount. This is equal to the greatest array index number set via DynArraySet 
or inserted via DynArraylnsert. It is also updated in DynArrayGetPtr, even if the user is getting the 
pointer to a cleared data pointer that has not been set or inserted. DynArrayGetPtr is also used during 
binary searches, and hence that fiinction will modify maxCount if the binary search expands to empty 
elements in the list. This is necessary because client functions can modify the contents of the element via 
DynArrayGetPtr, because they have direct access to the data. Typical users of dynamic arrays will not call 
DynArrayGetPtr in such a manner as to modify maxCount. 

In summary, entries is the amount of space allocated by the array, and maxCount is the number of 
elements set or inserted into the array. 

When memory is allocated for entries in the arr^, via DynArraylnsert, DynArrayNew, or 
DynArrayExpand, it is initialized to 0. 

tifndef DYNARRAY_INCLUDED 
tdefine DYNARRAY_INCLUDED 

tifndef GO_INCLUDED 

# include <go.h> 

#endif 

#ifndef OSHEAP_INCLUDED 

tinclude <osheap.h> 

#endif 
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Common #defines and typedefs 

Dynamic Array 

This data structure is the dynamic array data structure. A dynamic array created and manipulated is 
simply a pointer to this data structure that is passed to the dynarray functions. Accessing the fields in 
this data structure is possible, but care should be taken as changing their values could have drastic side 
afifects. This data structure is sometimes referred to as the array header. 

typedef struct DYNARRAY { 

OS_HEAP_ID heap; // heap used for allocations 

U16 entries; // total # entries in the array 

U16 elemSize; // size in bytes of individual elements 

P_U8 pData; // pointer to the array of values 

U16 maxCount; // Max index accessed in the array via 

// DynArraySet, DynArrayGetPtr, DynArrayBinSearch 
// Updated when inserting, deleting, or contracting 
// array. 
} DYNARRAY, *P_DYNARRAY; 

Public Functions 

DynArrayNew 

Allocates a new dynamic array. Passes back the P_DYNARRAY header. 

Returns STATUS. 

tim'i Prototype STATUS DynArrayNew ( 

OS_HEAP_ID heap, // In: heap for memory allocation 

// NULL=>osProcessHeapId 

U16 elementSize, // In: size in bytes of each array element 

U16 startSize, // In: initial array size in number of elements 

U16 extraHeader, // In: additional bytes to allocate in the header 

P_DYNARRAY *ppArray) ; // Out: pointer to the header pointer 

rtients Allocates memory for the array header, the P_DYNARRAY that is passed to the dynarray functions. 

Allocates memory for the initial elements in the array. Parameters include: the allocation heap to 
perform memory allocations, the size of an individual element, the initial size of the array 
(pArray->elements will the same as this value when this function returns), and any extra space to be 
allocated in the P_DYNARRAY pointer. This space can be used by clients to store list-wide information or 
flags. Passes back a pointer to the array data structure, P_DYNARRAY. 



DynArrayFree 

Destroys the dynamic array and frees memory used by the array. 

Returns STATUS. 

STATUS DynArrayFree ( 

P_DYNARRAY pArray) ; // In: array header. Will be freed. 

Will free all memory allocated by the array to store the header information and the elements. Does not 
do anything with the entries in the array. 
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DynArrayExpand 

Expands the array by the specified number of entries. 
Returns STATUS. 



Function Prototype STATUS DynArrayExpand { 
P_DYNARRAY pArray, 
U16 add); 



..ommenfs 



// In: array header 

// In: Number of elements to add 



Expands the array by a number of entries, updating pArray->entries, the returned value of calUng 
DynArrayCount, and the reallocation of pArray->pData to be equal to pArray->entries * 
pArray->elementSize. This function is called when calling DynArraylnsert to add space for one more 
entry. It is also called in DynArraySet if the index is greater than the number of entries. 

DynArraySet 



DynArrayContract 

Contracts the array by the number of entries. 

Returns STATUS. 

STATUS DynArrayContract ( 

P_DyNARRAY pArray, // In: array header 

U16 truncate); // In: Number of elements to free 

Will contract the number of entries in the array, and free the memory associated with those entries. Will 
resize the amount of memory allocated by the array pArray->pData to be pArray->entries * 
pArray->elementSize. If the maxCount (return code of DynArrayCount) is greater than the new 
number of entries allocated, maxCount will be adjusted. Called from DynArrayDelete to contract the 
array when deleting items. 

DynArrayDelete 



DynArrayGet 

Passes back the index'th element in the array. 
Returns STATUS. 



STATUS DynArrayGet ( 
P_DYNARRAY pArray, 
U16 index, 
P_UNKNOWN pData) ; 



// In: array header 

// In: element index 

// Out: pointer to data buffer. Must be elementSize. 



Will pass back the contents of the index'th element in the array. Will copy the memory of size 
elementSize containing the data for the element into pData. It is the clients responsibility to ensure that 
this data pointer is large enough. 



DynArraySet 

Sets the index'th item to the given value. Update maxCount. 
Returns STATUS. 



STATUS DynArraySet ( 
P_DYNARRAY pArray, 
U16 index, 
P_UNKNOWN pData) ; 



// In: array header 

// In: element index 

// In: pointer to data or NULL for zero fill 
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Zomnmmts Sets the contents of the index'th item to the given value. Will copy the contents of the pData pointer to 

the memory for the index'th element in the array. It is the clients responsibility to ensure that pData is 
correct. If index is greater than maxCount, it will update maxCount. If the index is greater than the 
number of entries, the array is expanded via DynArrayExpand to be large enough. Called from 
DynArraylnsert to set the value of the new index. 

See Also DynArraylnsert 

DynArrayGetPtr 

Passes back a pointer to the index'th element in the array. 

Returns STATUS. 

uincflon Prototype STATUS DynArrayGetPtr ( 

P_DYNARRAY pArray, // In: array header 

U16 index, // In: element index 

PP_UNKNOWN pData); // Out: pointer to data buffer 

Comments Will pass back the direct pointer to the index'th element in the dynamic array. Care should be taken 

when accessing this pointer, as it is memory that is allocated and managed by the array. Accessing the 
data in this manner WILL cause the maxCount to be increased if maxCount < index. This function is 
called during a binary search via DynArrayBinSearch. Hence that hinction could modify maxCount. 

iee Also DynArrayBinSearch 

DynArraylnsert 

Inserts a new element in the array. 

Returns STATUS. 

"yncflsri Pr€sfsf>'pe STATUS DynArraylnsert ( 

P_DYNARRAY pArray, // array header 
U16 index, // element index 

P_UNKNOWN pData // new data to insert or NULL 

); 

Coiiiriients The new element is indexed by index. If the array is not big enough, will expand the array appropriate!)^. 

Elements are copied from the index'th location to the next location. 

See Also DynArrayExpand 

DynArrayDelete 

Deletes the index'th element from the array. 

Returns STATUS. 

Functicm Prototype STATUS DynArrayDelete ( 

P_DYNARRAY pArray, // array header 
U16 index // element index to delete 

); 

Comments Will delete the index'th element from the array. If index is > entries, will return stsOK and do nothing. 

Will move all elements greater than the index down by one in the array. Will adjust maixCount if 
necessary. Will call DynArrayContract with parameter of one. 



DYNARRAY.H 645 

Public Functions 



DynArrayCount 

Passes back the number of entries allocated in the array. 

Returns STATUS. 

Functiors Prototype STATUS DynArrayCount ( 

P_DYNARRAY pArray, // In: array header 

P_U16 pCount) ; // Out: pointer to the count 

Comments Passes back the number of entries allocated in the array. This number is the amount of space allocated, 

and not the number of items stored in the array. That value is returned by DynArrayMax. 



DynArrayMax 

Passes back the highest index stored. 

Returns STATUS. 

Fusicfion Prototy|9e STATUS DynArrayMax ( 

P_DYNARRAY pArray, // In: array header 

P_U16 pMax) ; // Out: pointer to the max index 

Comments Will return the highest index stored via DynArraySet or DynArrayGetPtr, plus one. This is the 

"maxCount" field, and is used to indicate the highest array entry that has a valid value. 



DynArrayElemSize 

Passes back the size, in bytes, of each element. 
Returns STATUS. 

3 

unction Prstotype STATUS DynArrayElemSize ( S 

P_DYNARRAY pArray, // In: array header < 

P_U16 pSize) ; // Out: pointer to the size 3j 

omments Passes back the size allocate in the array for each element. The pArray->pData size will be the value ^ 

passed back by this function * the value passed back by DynArrayCount. ^ 



DynArrayBinSearch 

Performs a binary search on the array. 

Returns STATUS. 

typedef S16 FunctionPtr (P_BIN_PROC) (P_UNKNOWN, P_UNKNOWN) ; 

Argymenfs typedef struct DYNARRAY_SEARCH ( 

P_UNKNOWN pData; // In: Pointer to search data. 

U16 start; // In: start index, Out: first occurrence 

U16 stop; // In: end index, Out: last occurrence 

P_BIN_PROC pCompare;// In: routine to perform comparisons 
S16 result; // Out: if equal, -1 less, 1 greater 

} D YNARRAY_SEARCH , *P_DYNARRAY_SEARCH ; 

Fyncfion Prototype STATUS DynArrayBinSearch ( 

P_DYNARRAY pArray, // In: array header 

P_DYNARRAY_SEARCH pSearch) ; //In: search data 

Comments Performs a binary search on the array. Assumes that the array is "sorted" from lowest value to highest 

value. Will access the value of data in the array via DynArrayGetPtr. Hence care should be taken when 
using the data in the comparison callback routine. 

Retyrn Value stsNoMatch No matching data could be found within the range. 
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DynArrayGetPtr 

P_BIN_PROC is the comparison routine callback. Will be called to test items. Called parameters 
containing pointers to an element in the array, and a pointer to a test 'element' to check for comparison. 
Returns for equal, -1 for less, 1 for greater. 

DYNARRAY_SEARCH is the parameter into the DynArrayBinSearch hmction. Takes the search data 
pointer to locate, a starting index into the array to search, a stopping index into the array to search, and 
a comparison callback function to test the data pointer against elements in the array. If result is 0, passes 
back the starting and ending indices that match. If result is -1, the target data pointer was less than both 
the starting and ending indices searched. Similarly, if result is 1, the target data pointer was greater than 
both indices. 
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GOSEARCH.H 
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Fyncfion Protc 
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This file contains the API definition for GO's modified binary search. The fiinction described in this file 
is contained in MISC.LIB. 

The fiindamental difference between this binary search and the search that is part of the standard 
runtime is that if the search fails, this search indicates where a searched for element should have been 
located, thereby aiding insertion of a new element. 



tifndef GOSEARCH_INCLUDED 

tdefine GOSEARCH INCLUDED $Revision: 



1.6 $ 



tinclude <go. 


.h> 




tifndef GO_INCLUDED 
#endif 


typedef P_UNKNOWN 


(CDECL *ACCESS_FUNC) ( 
const P_UNKNOWN, 
const U32) ; 


// context 
// index 


typedef int 




(CDECL *COMPARE_FUNC) ( 
const P_UNKNOWN, 
const P_UNKNOWN, 
const P_UNKNOWN); 


// context 
// keyl 
// key2 



binaiySearch 

Performs a binary search for specified key within dataStructure. 

Returns STATUS. 

STATUS EXPORTED binarySearch ( 
const P_UNKNOWN key, 
const P UNKNOWN dataStructure, 



const U32 
COMPARE_FUNC 
ACCESS_FUNC 
const U16 
PP_UNKNOWN 
P U32 



count , 
compare, 
access, 
itemSize, 
pFoundOrlnsert , 
p Index) ; 



binaiySearch performs a binary search on a sorted, indexed data structure. 

The caller provides an count of the number of items in the data structure, an access fiinction that 
translates an item index into an address for the item key, and a comparison function to compare a pair 
of keys. 

A detailed description of the parameters follows. 

key key to search for. 

dataStructure handle of data structure to search. 

count number of items in data structure. 

compare pointer to comparison function (see below). 

access pointer to access function (see below). If Nil, dataStructure is assumed to be the address of a 
sorted, contiguous array of items (itemSize bytes long) with the item key at the start of each item. 
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itemSize size of item in bytes (only used if access is Nil). 

pFoundOrlnsert pointer to key (see below). 

pindex pointer to index (see below). 

The access function is provided with the client provided dataStructure and a (zero origin) index. It is 
responsible for returning the key for the indexed item. This key must be comprehensible to the 
comparison function, but is otherwise uninterpreted by the search. 

The comparison function is responsible for actually comparing two keys, and returning values as . 



follows. 

< 
== 
> 



when keyl < key2, 
when keyl == key2, 
when keyl > key2. 



keyl is always the key originally passed to binarySearch as a parameter. key2 is always a key generated 
from dataStructure by the access function. 

When binarySearch returns, *pFoundOrInsert contains either: 

the first occurrence of the desired key, if it was found; or 
NULL, if the key was not found but was greater than the keys 

of all the items in dataStructure; or 
the first key larger than the desired key. 

In addition, when binarySearch returns, *plndex contains either count, if *pFoundOrInsert == NULL, 
or the index used to access the key returned via *pFoundOrInsert. 

The return value is: 

stsOK if desired key located, or 

stsNoMatch if desired key not located 






m^j, 






PDICT.H 



This file contains the Personal Dictionary Class API. This class contains methods that maintain an 
ordered ASCII list of words and can produce a compressed list (called the template), which is specially 
organized for use with handwriting translation software. 

clsPDict inherits from clsObject. 

thePersonalDictionary is a well known instance of clsPDict. 

The word list maintained by thePersonalDictionary is used by default whenever spelling-assisted 
handwriting translation is performed. 

Abo spell.h 

tifndef PDICT_INCLUDED 
tdefine PDICT_INCLUDED 

tifndef FS_INCLUDED 
tinclude <uuid.h> 
tinclude <fs.h> 
#endif 

fifndef INSTLMGR_INCLUDED 
tinclude <instlmgr.h> 
tendif 

Common typedefs 

Personal Dictionary Metrics 

This structure is used in conjunction with msgPDictGetMetrics to get two very important parameters 
of a personal dictionary: the number of words in it and a pointer to the compressed template. The word 
count is usefijl for a variety of things, but the compressed template is valuable because it can be used 
directly in the pTemplate field of a translator object (see xlate.h) 

typedef struct PDICT_METRICS { 

U16 wordCount; // number of words in the personal dictionary (RO) 

P_UNKNOWN pXTemplate; // pointer to compressed template 
} PDICT METRICS, * P PDICT METRICS; 



Personal Dictionary Nevsr Structs 



typedef struct PDICT_NEW_ONLY { 
IM_HANDLE handle; 

U32 spare; 

} PDICT_NEW_ONLY, * P_PDICT_NEW_ONLY; 

typedef struct PDICT_NEW { 

OBJECT_NEW_ONLY object; 
PDICT_NEW_ONLY pdict; 

} PDICT NEW, * P PDICT NEW; 



// if objNull then use current pdict. 
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Miscellaneous 



This structure is used for converting a word index into a word and vice versa. (That is, for example, to 
get word #5 from the PDict or to find out which word number in the PDict "PenPoint" is.) 

typedef struct PDICT_NUM_WORD { 

U16 number; 

P_CHAR pWord; 
} PDICT NUM WORD, * P PDICT NUM WORD; 



Messages 



msgPDictGetMetrics 

Gets a copy of the personal dictionary metrics structure. 

Takes P_PDICT_METRICS, returns STATUS. 

fdefine msgPDictGetMetrics MakeMsg(clsPDict,l) 

Message typedef struct PDICT_METRICS { 

Argomenfs U16 wordCount; // number of words in the personal dictionary (RO) 

P_UNKNOWN pXTemplate; // pointer to compressed template 
} PDICT_METRICS, * P_PDICT_METRICS; 

This is mainly useful to find out how many words are in thedictionary. 

msgPDictEnumerateWords 

Fills a list of pointers to strings with pointers to all the words in the personal dictionary. 

Takes PP_CHAR, returns STATUS. 

#define msgPDictEnumerateWords MakeMsg{clsPDict,2) 

The pArgs must be the address of the base of an array of pointers tofilled in. This array must have an 
entry for every word in thedictionary plus one for the final null (get the metrics toout how many 
words are in the PDict. The words will be in ASCIIsequence, and because the pointers all point to 
an internalstructure, no memory is allocated. N.B. you must treat thisas strictly read-only! 

Adds a word to the personal dictionary. 

Takes P_PDICT_NUM_WORD, returns STATUS. 

#define msgPDictAddWord MakeMsg(clsPDict,3) 

Message typedef struct PDICT_NUM_WORD { 

Argtimenfs U16 number; 

P_CHAR pWord; 

} PDICT_NUM_WORD, * P_PDICT_NUM_WORD; 

The routine SpellAddWord(), defined in spell.h, is a better way forclients to add words to the Personal 
Dictionary, since it has aAPI, strips excess punctuation, checks for duplicates, etc. 

msgPDictAddWord adds the string from the PDICT_NUM_WORD structure,the zero-based offset of the 
new word in the personal, and passes back that offset in the number component 
ofPDICT_NUM_WORD structure. 

Although the ASCII representation of the Personal Dictionary isimmediately, the compressed template 
is not rebuilt until thetime msgPDictUpdateTemplate is called. Handwriting Translationthis 
automatically when it needs the template, but spelling does. 
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msgPDictDeleteWord 

Deletes a word from the personal dictionary. 

Takes P_PDICT_NUM_WORD, returns STATUS. 

tdefine msgPDictDeleteWord MakeMsg(clsPDict,4) 

Message typedef struct PDICT_NUM_WORD { 

irgwments U16 number; 

P_CHAR pWord; 

} PDICT_NUM_WORD, * P_PDICT_NUM_WORD; 

The reverse of msgPDictAddWord, this message removes the word frompersonal dictionary and passes 
back the zero-based offset of thewhere it formerly was. 

Like msgPDictAddWord, this only affects the ASCII representation ofPersonal Dictionary. The next 
handwriting translation operationrebuild the template, but if you need it built before that (for, to 
change the behavior of spelling), send. 

msgPDictNumToWord 

Locates a word in the personal dictionary by index number, passing back the word at that offset. 

Takes P_PDICT_NUM_WORD, returns STATUS. 

tdefine msgPDictNumToWord MakeMsg(clsPDict,5) 

tessage typedef struct PDICT_NUM_WORD { 

krgwmenfs U16 number; 

P_CHAR pWord; 

} PDICT_NUM_WORD, * P_PDICT_NUM_WORD; 

I/) 
Words are indexed in ASCII collating sequence from zero. 5 

Ul 

Z 

msgPDictFindWord 

Checks if a word is in the personal dictionary. 

Takes P_CHAR, returns STATUS. 

tdefine msgPDictFindWord MakeMsg(clsPDict, 6) 

stsOK means it was found; stsFailed means it was not. 



msgPDictDeleteNum 

Locates a word in the personal dictionary by index number and deletes the word at that offset. 

Takes P_PDICT_NUM_WORD, returns STATUS. 

tdefine msgPDictDeleteNum MakeMsg(clsPDict,7) 

ssage typedef struct PDICT_NUM_WORD { 

lumeRfs U16 number; 

P_CHAR pWord; 

} PDICT_NUM_WORD, * P_PDICT_NUM_WORD; 

Words are indexed in ASCII collating sequence from zero. The numberthe word to delete is the number 

field from the PDICT_NUM_WORD; the actual word deleted is passed back in pWord. (This 

MUSTset to point to something by the caller! Max size is+ 1 . Setting pWord to Nil(P_CHAR) passes 

nothing back.) 
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msgPDictWordToNum 

Given a word, computes its offset within the personal dictionary. 

Takes P_PDICT_NUM_WORD, returns STATUS. 

tdefine msgPDictWordToNum MakeMsg{clsPDict,8) 

typedef struct PDICT_NUM_WORD { 

U16 number; 

P_CHAR pWord; 
} PDICT_NUM_WORD, * P_PDICT_NUM_WORD; 

Words are counted from zero in ASCII collating sequence. 

msgPDictUpdateTemplate 

Recomputes the compressed template from the word list and updates the pointer. 

Takes PP_UNKNOWN, returns STATUS. 

#define msgPDictUpdateTemplate MakeMsg(clsPDict,9) 

When the ASCII form of the personal dictionary is modified, thetemplate is not automatically 

modified. Since compressionbe time consuming, this is deferred until it is absolutely. This routine is 

called by Handwriting Translation at theof every translation. 

If the current template is not out of date, this just copies old value intoargument. 



Miscellaneous 



Base of the template of thePersonalDictionary. Handwritingneeds to be able to get at this very quickfy^, 
so it'sas an exported global variable to allow it to avoid the. 

extern P_UNKNOWN PASCAL pPDictBase; 

tdefine hlpPDAppBackground MakeTag(clsPDApp, 1) 






POWER.H 



This file contains the API definition for class clsPowerButton. 

clsPowerButton inherits fi:om clsObject. 

"thePowerButton" is a well known object that provides notification when the machine is turned ofFand 
on. 

tifndef POWER_INCLUDED 
tdefine POWER_INCLUDED 

tifndef GO_INCLUDED 

tinclude <go.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

#endif 



Messages 



Comitien 



msgPBMachinePoweringUp 

Notifies clients that the machine is powering up. 

Takes nothing, returns nothing. Category: observer notification, 

#define msgPBMachinePoweringUp MakeMsg (clsPowerButton, 1) 

Sent by the system to observers of thePowerButton, Indicates that the machine is in the process of 
powering up. 

The system will not power up until all observers of thePowerButton are notified. The system will wait 
until the notification message has completed for each client. 

msgPBMachinePoweringDown 

Notifies clients that the machine is powering down. 

Takes nothing, returns nothing. Category: observer notification. 

♦define msgPBMachinePoweringDown MakeMsg (clsPowerButton, 2) 

Sent by the system to observers of thePowerButton. Indicates that the machine is in the process of 
powering down. 

Most applications do not need to observe the power button, since theSystem sends the appropriate 
messages to all applications and services when the machine powers down. 

The system will not power down until all observers of thePowerButton are notified. The system will 
wait until the notification message has completed for each client. 









POWERMGR.H 



This file contains the API definition for class clsPowerMgr. 

clsPowerMgr inherits from clsObject. 

"thePowerMgr" is a well known object that provides system power management. 

#ifndef POWERMGR_INCLUDED 
#define POWERMGR_INCLUDED 

#ifndef GO_INCLUDED 

#include <go.h> 

#endif 

#ifndef CLSMGR_INCLUDED 

#include <clsmgr.h> 

#endif 



Common #clefiiies and typedefs 



typedef U16 
typedef U16 



PM_POWER_STATE; 

PM POWER METRICS, *P PM POWER METRICS; 



Messages 



msgPMSetPowerState 

Sets the machine power state. 

Takes PM_POWER_STATE, returns nothing. 

♦define msgPMSetPowerState MakeMsg (clsPowerMgr, 1) 

♦define pmStandby flagO // power down to stand by state, 
♦define pmPowerOff flagl // power down to complete off. 
♦define pmForceBoot flag2 // Force a cold boot on the machine 
♦define pmQuickestPowerOnState (pmStandby | pmPowerOff) 

// quickest allowable power on state. 

Initiates the powering down of the machine. The machine can be powered down in "standby" state (i.e. 
RAM is maintained, but the rest of the system is shut down) or "complete off state. 

Powering down the machine will force all data to be saved to disk (if applicable) and will notify all 
observers of the power button of this event (see power.h). 

If the client is unfamiliar with the hardware configurations, use pmQuickestPowerOnState. This mode 
will power down the machine to the state that will cause the machine to come up in the quickest 
possible time. 

pmForceBoot will force the machine to reset and cold boot the software. Caution: Under certain 
configurations this may cause loss of data!!! Specifically, under a RAM only configuration, all the 
contents of RAM will be lost. 
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msgPMGetPowerMetrics 

Passes back the machine power information. 
Takes P_PM_POWER_METRICS, returns STATUS. 

#define msgPMGetPowerMetrics MakeMsg{clsPowerMgr, 2) 

#define pmStandbyPowerSupported flagO // only ram is alive 

tdefine pmNoPowerSupported flagl // everything is off 

tdefine pmStandbyButtonSupported flag2 // power button usage 

#define pmChargerConnectedSupported flag3 // power connection 

fdefine pmldleStateSavesPower flag4 // idle = low power state? 

#define pmChargerConnected flagS // is power connected? 

tdefine pmSomeDevicePoweredDown flaglS // something is off 

Slits Passes back information on what power states are supported on this machine. The machine can support 

either 1) standby or 2) power off or 3) both or 4) none. Setting none indicates that the software is 
unable to change the power state of the machine. 

This message also returns information on the charger and whether a standby button is supported. 

msgPMDevicesPowerOn 

Turns power on to all devices in the system. 

Takes nothing, returns STATUS. 

#define msgPMDevicesPowerOn MakeMsg(clsPowerMgr, 3) 

msgPMDevicePoweringOn 

Notifies observers that a device is powering up. 

Takes U16, returns nothing. Category: observer notification. 

tdefine msgPMDevicePoweringOn MakeMsg(clsPowerMgr, 4) 

nents Sent by the system to observers of thePowerMgr. Indicates that a device (specified by MIL logical Id) is 

powering up. 

msgPMDevicePoweringOff 

Notifies observers that a device is powering down. 

Takes U16, returns nothing. Category: observer notification. 

tdefine msgPMDevicePoweringOff MakeMsg(clsPowerMgr, 5) 

iieofs Sent by the system to observers of thePowerMgr. Indicates that a device (specified by MIL logical Id) is 

powering off 



msgPMAllDevicesPoweredOn 

Notifies observers that all devices have powered up. 
Takes nothing, returns nothing. Category: observer notification, 
tdefine msgPMAllDevicesPoweredOn MakeMsg(clsPowerMgr, 6) 

Sent by the system to observers of thePowerMgr. 






/li*!!::!!^^ 



APIl denotes PenPoint API Reference, Volume I API2 denotes PenPoint API Reference, Volume II 



AB_MGR_CHANGE_TYPE, APl2:349 

AB_MGRJD, APl2:345-348 

AB_MGR_ID_TYPE, APl2:345 

AB_MGR_LIST, APl2:347 

AB_MGR_NOTIFY, APl2:349 

Abs, API 1:56 

AcetateClear, API 1:628 

AcetateClearDisable, API 1:628 

AcetateClearRect, API 1:629 

AcetateCursorFreezePosition, API 1:628 

AcetateCursorlmage, API 1:628 

AcetateCursorRequestVisible, API 1 :627 

AcetateCursorThaw, API 1:627 

AcetateCursorUpdatelmage, API 1 :628 

AcetateCursorXY, APIl:628 

AcetateTransform, API 1:627 

AddListltem, APl2:78 

AddListltemX, API2:77 

ADDR_BOOK_ATTR, APl2:354, APl2:36l 

ADDR_BOOK_ATTR_DESC, APl2:354 

ADDR_BOOK_ATTR_OPS, APl2:358 

ADDR_BOOK_CHANGE_TYPE, APl2:363 

ADDR_BOOK_COUNT, APl2:362 

ADDR_BOOK_ENTRY, APl2:354-358 

ADDR_BOOK_ENTRY_CHANGE, APl2:363 

ADDR_BOOK_ENTRY_TYPE, APl2:354 

ADDR_BOOK_ENUM_GROUP_MEMBER, 
API2:360 

ADDR_BOOK_IS_A_MEMBER_OF, APl2:36 1 
ADDR_BOOK_METRICS, APl2:36l 
ADDR_BOOK_QUERY, APl2:359 
ADDR_BOOK_QUERY_ATTR, APl2:359 
ADDR_BOOK_SEARCH, API2:359 
ADDR_BOOK_SEARCH_DIR, APl2:358 
ADDR_BOOK_SEARCH_TYPE, APl2:358 
ADDR_BOOK_SERVICE, APl2:354 
ADDR_BOOK_SERVICE_QUAL, APl2:354 
ADDR_BOOK_SERVICES, APl2:360 
ADDR_BOOK_SVC_DESC, APl2:360 
ADDR_BOOK_VALUE_OPS, APl2:359 
ADDRESS, API2:4 19 
ADDRESS_ACQUIRE, APl2:422 
AIM_NEW, API2:514 
ALAP_HSLINK_NEW, APl2:393 
ALARM_NOTIFY, APl2:180 
AM_METRICS, API 1 : 1 30 



AM_TERMINATE_VETOED, API 1 : 1 35 
ANI]V[_SPAPER_NEW, API 1:632-633 
ANIM_SPAPER_NEW_ONLY, API 1:632 
ANIM_SPAPER_SCRIBBLE, API 1 :633-634 
ANM_ATTR_AUX_NB, APl2: 5 1 8 
ANM_ATTR_NO_LOAD, APl2:518 
ANM_ATTR_PERMANENT, APl2:523 
ANM_ATTR_STATIONERY_MENU, 
API2:518 

ANM_AUX_NOTEBOOK, APl2:517 
ANM_CREATE_DOC, APl2:519 
ANM_CREATE_SECT, APl2:519 
ANM_DELETE, API2:521 
ANM_DELETE_ALL, APl2:521 
ANM_EXIST_BEHAVIOR, APl2:518 
ANM_GET_MENU, APl2:522 
ANM_GET_NOTEBOOK_PATH, APl2:521 
ANM_GET_NOTEBOOK_UUID, APl2:521 
ANM_MENU_ADD_REMOVE, APl2:523 
ANM_MENU_NAME_CHANGED, APl2:523 
ANM_MOVE_COPY_DOC, APl2:520 
ANM_NEW, API2:519 
ANM_OPEN_NOTEBOOK, APl2:522 
ANM_POP_UP_MENU, APl2:522 
APP_ACTIVATE_CHILD, API 1:89 
APP_BORDER_METRICS, API 1:97 
APP_CHANGED, API 1 : 1 08 
APP_CHILD_CHANGED, API 1 : 1 06 
APP_CREATED, API 1 : 1 06 
APP_DELETED, API 1 : 1 06 
APP_DIR_ATTRS, API 1 : 1 1 2 
APP_DIR_FLAGS, API 1 : 1 1 2 
APP_DIR_GET_BOOKMARK, API 1 : 1 1 6 
APP_DIR_GET_GLOBAL_SEQUENCE, 
API1:116 

APP_DIR_GET_SET_ATTRS, API 1 : 1 1 3 
APP_DIR_GET_SET_FLAGS, APll:l 13 
APP_DIR_NEXT, API 1 : 1 1 7 
APP_DIR_SEQ_TO_NAME, APll:l 17 
APP_DIR_SET_BOOKMARK, API 1 : 1 1 6 
APP_DIR_UPDATE_CLASS, APll:l 14 
APP_DIR_UPDATE_NUM_CHILDREN, 

API1:115 
APP_DIR_UPDATE_SEQUENCE, API 1 : 1 1 5 
APP_DIR_UPDATE_UID, API 1 : 1 14-1 1 5 
APP_DIR_UPDATE_UUID, API 1 : 1 14 
APP_EXECUTE, API 1 : 1 04 



APP_FIND_FLOATING_WIN, API 1:90 
APP_FLAGS, API 1:81 
APP_FLOATED, API 1 : 1 06 
APP_GET_APP_WIN, API 1:94 
APP_GET_EMBEDDED_WIN, API 1:93 
APP_GET_OPTION_SHEET, API 1:95 
APP_LINK, API 1:99-1 00 
APP_METRICS, API 1:82, API 1:87 
APP_MGR_ACTIVATE, API 1 : 1 23 
APP_MGR_CREATE, APIl: 122 
APP_MGR_DELETE, API 1 : 1 24 
APP_MGR_FLAGS, API 1 : 1 20 
APP_MGR_FS_MOVE_COPY, API 1:124 
APP_MGR_GET_RES_LIST, API 1:126 
APP_MGR_GET_ROOT, API 1 : 1 25 
APP_MGR_METRICS, API 1 : 1 20, API 1 : 1 22 
APP_MGR_MOVE_COPY, API 1:123-124 
APP_MGR_MOVE_COPY_STYLE, API 1 : 1 23 
APP_MGR_NEW, API 1 : 1 2 1 
APP_MGR_RENAME, API 1 : 1 25 
APP_MOVED_COPIED, API 1 : 1 07 
APP_NEW, API 1:83-84 
APP_NEW_ONLY, API 1:83 
APP_OPEN, API 1:86 
APP_OPEN_CHILD, API 1:92 
APP_OWNS_SELECTION, API 1:94 
APP_SHOW_OPTION_SHEET, API 1:96 
APP_WIN_METRICS, APll:l45 
APP_WIN_NEW, API 1 : 1 44 
APP_WIN_NEW_ONLY, API 1 : 1 44 
APP_WIN_STYLE, API 1:144, APIl: 146 
AppDebug, API 1:79 
AppMain, APIl: 109 
AppMonitorMain, API 1:109 
ASSERT, API 1:48 
AtomGetName, APl2: 1 1 
ATP_ADDRESS, APl2:365 
ATP_OPTIONS, API2:365 
ATP_RESPPKTSIZE, APl2:367 
ATTRIB, API2:371 
ATTRIBUTES_GET, APl2:422 



BAFileReadString, APl2:204 
BAFileWriteString, APl2:203 
BATTERY_METRICS, APl2:639 
binary-Search, APl2:647 



658 



INDEX 



BITMAP_NEW, API 1 :226 
BITMAP_NEW_ONLY, API 1:226 
BITMAP_PIX_CHANGE, API 1:227 
BITMAP_STYLE, API 1:225 
BLOCK, API2:4 19 

BOOKSHELF_METRICS, APl2: 183-1 84 
BOOKSHELF_NEW, APl2:183 
BOOKSHELF_NEW_ONLY, APl2:183 
BOOLEAN, API 1:56 
BORDER_BACKGROUND, API 1:340 
BORDER_NEW, API 1:331 
BORDER_NEW_ONLY, API 1:331 
BORDER_STYLE, API 1:330, 

API 1:332-334, API 1:337 
BORDER_UNITS, API 1:336 
Borderink, API 1:328 
BorderUnits, API 1:329 
Border UnitsCustom, API 1:329 
BorderUnitsMult, API 1:329 
BROWJUSTIFY, 7^12:191 
BROWSER_BOOKMARK, API2:196 
BROWSER_COLUMN, APl2:191 
BROWSER_COLUMN_STATE, API2:192 
BROWSER_CREATE_DOC, APl2:196 
BROWSER_DEF_COLUMN, APl2: 1 9 1 
BROWSER_GESTURE, APl2:197 
BROWSER_GOTO, APl2:194 
BROWSER_METRICS, APl2: 1 9 1 
BROWSER_NEW, APl2:187 
BROWSER_NEW_ONLY, API2:187 
BROWSER_PATH, APl2:195 
fiROWSER_USER_COLUMN, APl2: 1 92-1 93 
BUFFER_RETURN, APl2:421 
BUTTON_NEW, API 1:349 
BUTTON_NEW_ONLY, API 1:348 
BUTTON_NOTIFY, API 1:348, API 1:353 
BUTTON_STYLE, API 1:348, API 1:350 
BYTE_ARRAY, APl2:199 
ByteArrayCreate, APl2:201 
ByteArrayDelete, APl2:202 
ByteArrayDestroy, APl2:201 
ByteArrayFindByte, API2:200 
ByteArrayFindlndex, APl2:200 
ByteArrayGapLength, APl2:199 
ByteArrayGetByte, API2:200 
ByteArrayGetMany, API2:201 
ByteArrayHeapMode, APl2:202 
ByteArraylnsert, APl2:202 
ByteArrayLength, API2:202 
ByteArrayPrint, API2:200 
ByteArrayRead, API2:203 



ByteArrayReplace, APl2:201 
ByteArrayReserve, APl2:202 
ByteArrayWrite, API2:203 
BYTEBUF_DATA, APl2:205-206 
BYTEBUF_NEW, APl2:205-206 
BYTEBUF_NEW_ONLY, APl2:205 



CcittDecode3 1 , API 1 :230 
CcittEncode3 1 , API 1 :230 
CG_GET_OWNER, APl2:589 
CG_OWNER_NOTIFY, APl2:591 
CG_SET_OWNER, APl2:590 
CHARACTER_MEMORY, API 1:744 
CHOICE_MGR_NEW, API 1:357 
CHOICE_MGR_NEW_ONLY, API 1:357 
CHOICE_NEW, API 1:359-360 
CHOICE_NEW_ONLY, API 1:359 
CHOICE_STYLE, API 1:359-360 
CIM_ATTR_DEINSTALLABLE, APl2:526 
CIM_FIND_CLASS, APl2:526 
CIM_FIND_PROGRAM, APl2:527 
CIM_GET_CLASS, APl2:526 
CIM_LOAD, API2:527 
CIM_TERMINATE, APl2:527 
CIM_TERMINATE_OK, APl2:527 
CIM_TERMINATE_VETOED, APl2:526, 
API2:528 

ClAlign, API 1:366 
CLASSJNFO, API 1:36 
CLASS_NEW, APIl:6 
CLASS_NEW_ONLY, API 1:6 
ClChildEdge, API 1:366 
ClConstraint, API 1:366 
ClExtend, API 1:366 
CLOSE_BOX_NEW, API 1:371 
CLOSE_BOX_NEW_ONLY, API 1:371 
CLOSE_BOX_STYLE, API 1:37 1-372 
ClRelWinEdge, API 1:366 
CLS_SYM_MSG, APIl:7 
CLS_SYM_OBJ, APll:7 
CLS_SYM_STS, APll:7 
ClsClearStatistics, API 1:37 
ClsDumpStatistics, API 1:37 
ClsMsgToString, API 1:33 
ClsNum, APIl:9 
ClsObjToString, API 1:33 
ClsSetStatistics, API 1:37 
ClsStatistics, API 1:37 
ClsStringToMsg, API 1:34 
ClsStringToObj, API 1:34 



ClsStringToSts, API 1:34 
ClsStringToTag, APIl:34 
ClsStsToString, API 1:32 
ClsSymbolsInit, API 1:34 
ClsTagToString, API 1:33 
COMMAND_BAR_NEW, API 1:373 
COMMAND_BAR_NEW_ONLY, API 1:373 
COMMAND_BAR_STYLE, API 1:373-374 

CONNECTIONS_COMPARE, APl2:372, 

API2:376 
CONNECTIONS_CONNECT_STATE, 

API2:370 
CONNECTIONS_ENUMERATE, 

APl2:371-372 

CONNECTIONSJTEM, APl2:370 
CONNECTIONS_MENU_ITEM, APl2:370 
CONNECTIONS_NOTIFY, APl2:376-377 
CONNECTIONS_PASSWORDS, APl2:370 
CONNECTIONS_PERMISSIONS, APl2:370 
CONNECTIONS_REQUEST, APl2:374-375 
CONNECTIONS_SERVICE_INFO, API2:373 
CONNECTIONS_STATE, APl2:370-371 
CONNECTIONS_TAG, APl2:372 
CONNECTIONS_TAG_ITEM, API2:373 
CONNECTIONS_WARNINGS, API2:370 
CONTROL_ENABLE, API 1:379 
CONTROL_NEW, API 1 :376 
CONTROL_NEW_ONLY, API 1:376 
CONTROL_PROVIDE_ENABLE, API 1:381 
CONTROL_STRING, API 1:376 
CONTROL_STYLE, API 1:375, API 1:377 
Coord l6from32, API 1:234 
Coord32To 16, API 1:234 
CORKBOARD_WIN_NEW, API 1 : 1 50 
CORKBOARD_WIN_NEW_ONLY, APIl:l49 
COUNTER_ACTION, API 1:386 
COUNTER_NEW, API 1:384 
COUNTER_NEW_ONLY, API 1 :383 
COUNTER_NOTIFY, API 1:386 
COUNTER_STYLE, API 1:383-384 

CSTM_LAYOUT_CHILD_SPEC, API 1:366, 

API 1:368-369 
CSTM_LAYOUT_CONSTRAINT, API 1:365 
CSTM_LAYOUT_DIMENSION, API 1:366 
CSTM_LAYOUT_METRICS, API 1 :365 , 

API 1:367 
CSTM_LAYOUT_NEW, API 1:367 
CSTM_LAYOUT_SPEC, APll :366 

CSTM_LAYOUT_STYLE, API 1:365, 

API 1:368 
CstmLayoutSpecInit, API 1:368 
CURRENT_STD_PEN_DATA, API 1:708 



INDEX 



659 



DATE_FIELD_NEW, API 1 : 5 86 
DATE_FIELD_NEW_ONLY, API 1 : 5 86 
DATE_FIELD_STYLE, APIl:585-586 
Dbg, API 1:48 
DbgFlag, API 1:48 
DbgFlagGet, API 1:50 
DbgFlagSet, API 1:49 
Debugf, API 1:49 
Debugger, API2: 148 
DECODE31, API 1:229 
DIALENV_AREA_CITY, APl2:383 
DIALENV_BUILD_DIALSTR, APl2:385 
DIALENV_COUNTRY, APl2:383 
DIALENV_DIAL_STRING, APl2:384 
DIALENV_ENVIRONMENT, APl2:384 
DIALENV_FIELD_NEW, APl2:388-389 
DIALENV_INTL_ACCESS, APl2:384 
DIALENV_LONG_DIST, APl2:384 
DIALENV_MACRO_CODE, APl2:384 
DIALENV_MACRO_IDS, APl2:386 
DIALENV_NEW, APl2:385 
DIALENV_OPTCARD_NEW, APl2:387-388 
DIALENV_OPTCARD_NEW_ONLY, 

API2:387 
DIALENV_OUTSIDE_LINE, APl2:383 
DIALENV_SUFFIX, APl2:384 

DIALENV_TELEPHONE_NUMBER, 
API2:384 

DIR_ID_CACHE, APl2:86 
DirldGetParent, APl2:95 
DPrintf, API 1:49 
DumpRect, API 1:239 
DV_GET_OPEN_VOLS, APl2:21 1 
DV_NEW, API2:209 
DV_NEW_ONLY, APl2:208 
DV_STYLE, API2:208, APl2:210 
DYN_TABLE_FIND_BUTTON, APl2:531 
DYN_TABLE_NEW, APl2:530 
DYN_TABLE_NEW_ONLY, APl2:530 
DYN_TABLE_STYLE, APl2:529 
DYNARRAY, APl2:642 
DYNARRAY_SEARCH, APl2:645 
DynArrayBinSearch, APl2: 64 5 
DynArrayContract, API2:643 
DynArrayCount, APl2:645 
DynArrayDelete, APl2:644 
DynArrayElemSize, API2:645 
DynArrayExpand, APl2:643 
DynArrayFree, APl2:642 



DynArrayGet, APl2:643 
DynArrayGetPtr, API2:644 
DynArraylnsert, APl2:644 
DynArrayMax, APl2:645 
DynArrayNew, APl2:642 
DynArraySet, APl2:643 
DynResId, API2:493 



EMBEDDED_WIN_BEGIN_MOVE_COPY, 

API1:161 
EMBEDDED_WIN_GET_DEST, APll:l64 
EMBEDDED_WIN_INSERT_CHILD, 

API1:165 
EMBEDDED_WIN_METRICS, API 1 : 1 74 
EMBEDDED_WIN_MOVE_COPY, 

API1:162-163 
EMBEDDED_WIN_MOVE_COPY_OK, 

API1:163 
EMBEDDED_WIN_NEW, APll:174 
EMBEDDED_WIN_NEW_ONLY, API 1 : 1 74 
EMBEDDED_WIN_PROVIDE_ICON, 

API1:162 
EMBEDDED_WIN_SHOW_CHILD, 

API1:166 
EMBEDDED_WIN_STYLE, APIl:173 
EMBEDDEE_PRINT_INFO, API 1:205 
ENCODE31, API 1:229 
ENUM_CALLBACK, APl2:255 
ENUMJTEMS, APl2:256 
ENUM_RECT_ITEMS, APl2:255 
Enuml6, API1:55 
Enum32, API 1:55 
Even, API 1:56 
EXCL_VOL_ACCESS, APl2:98 
EXPORT_DOC, API2:216 
EXPORT_FORMAT, APl2:2l6-217 
EXPORT_LIST, API2:216 



FIELD_ACTIVATE_POPUP, APIl:395 
FIELD_CREATE_POPUP, API 1:396 
FIELD_NEW, API 1:392 
FIELD_NEW_ONLY, API 1:392 
FIELD_NOTIFY, API 1:391, API 1:399 
FIELD_STYLE, API 1 :39 1 , API 1 :393 
FIELD_XLATE, API 1:392 
FIM_FIND_ID, API2:535 
FIM_GET_INSTALLED_ID_LIST, APl2: 536 
FIM_GET_NAME_FROM_ID, APl2:535 
FIM_GET_SET_ID, APl2: 534-535 
FIM_LONG_ID, API2:534 



FIM_NEW, API2:534 
FIM_PRUNE_CONTROL, APl2:536 
FindListltem, APl2:78 
FindListltemX, APl2:77 
FIXED_FIELD_NEW, API 1:588 
FIXED_FIELD_NEW_ONLY, API 1:588 
FIXED_FIELD_STYLE, API 1:587-588 
FlagClr, API 1:56 
FlagOff, API 1:56 
FlagOn, API 1:56 
FlagSet, API 1:56 
FLAP_NEW, API2:391 
FONTLB_NEW, API 1:40 1-402 
FONTLB_NEW_ONLY, API 1:401 
FONTLB_STYLE, API 1:40 1-402 
FRAME_NEW, API 1:406-407 
FRAME_NEW_ONLY, API 1:406 
FRAME_STYLE, API 1:405, API 1:408-409 
FRAME_ZOOM, API 1:405, API 1:4 13 
FS_CHANGEJNFO, APl2:68 
FS_CONNECT_VOL, APl2:97 
FS_DIR_NEW_MODE, APl2:58 
FS_DISCONNECT_VOL, API2:97 
FS_EXCL_VOL_ACCESS, APl2:98 
FS_EXIST, API2:57 
FS_FILE_NEW_MODE, APl2:58 
FS_FLAT_LOCATOR, APl2:56 
FS_GET_PATH, APl2:63 
FS_GET_PATH_MODE, APl2:58 
FS_GET_SET_ATTR, APl2:63 
FS_GET_VOL_METRICS, APl2:6l 
FS_INSTALL_VOL, APl2:96 
FS_LOCATOR, APl2:56, API2:69 
FS_MAKE_NATIVE, APl2:67 
FS_MOVE_COPY, APl2:64-65 
FS_MOVE_COPY_EXIST, APl2:57 
FS_MOVE_COPY_MODE, API2:58 
FS_MOVE_COPY_NOTIFY, API2:66 
FS_NEW, API2: 59-60 
FS_NEW_ONLY, APl2:59 
FS_NODE_EXISTS, APl2:62 
FS_NODE_FLAGS, APl2:56 
FS_NODE_FLAGS_ATTR, APl2:56 
FS_NOTIFY_OP, API2:66 
FS_NOTIFY_RTN_INFO, APl2:66 
FS_NOTIFY_TIME, APl2:65 
FS_READ_DIR, APl2:69 
FS_READ_DIR_FULL, APl2:70 
FS_REGISTER_VOL_CLASS, APl2:96 
FS_REMOVE_VOL, APl2:97 



660 



INDEX 



FS_SEEK, API2:72 
FS_SEEK_MODE, APl2:59 
FS_SET_HANDLE_MODE, APl2:62 
FS_SET_SIZE, API2:72 
FS_TRAVERSE, APl2:70 
FS_TRAVERSE_MODE, APl2:58 
FS_UPDATE_VOLS_MODE, APl2:98 
FS_VOL_CHANGE_FLAGS, APl2:69 
FS_VOL_CHANGEJNFO, APl2:69 
FS_VOL_FLAGS, APl2:57 
FS_VOL_HEADER, APl2:57 
FS_VOL_LIST, API2:97 
FS_VOL_LIST_ACCESS, APl2:97 
FS_VOL_SPECIFIC, APl2:68 
FS_VOL_TYPE, API2:56 
FSAttr, API2:54 
FSAttrCls, API2:54 
FSAttrIsFix32, API2:54 
FSAttrIsFix64, APl2:54 
FSAttrlsStr, APl2:54 
FSAttrlsVar, APl2:54 
FSMakeAttr, API2:54 
FSMakeFix32Attr, API2:54 
FSMakeFix64Attr, API2:54 
FSMakeStrAttr, APl2:54 
FSMakeVarAttr, APl2:54 
FSNameValid, API2:73 
FxAbs,APl2:127 
FxAdd,APl2:124 
FxAddSC,APl2:124 
FxArcTanFx,APl2:127 
FxArcTanInt, API2:127 
FxBinToStr,APl2:128 
FxChop,APl2:128 
FxChopSC,APl2:128 
FxCmp,APl2:123 
FxCos,APl2:126 
FxCosFx,APl2:127 
FxDiv,APl2:125 
FxDivInts, API2:126 
FxDivIntsSC,APl2:126 
FxDivIntToInt,APl2:126 
FxDivIntToIntSC, API2:126 
FxDivSC,APl2:125 
FxFraction, API2:128 
FxIntToFx,APl2:128 
FxMakeFixed, APl2:128 
FxMul,APl2:124 
FxMulInt,APl2:125 
FxMulIntSC,APl2:125 



FxMulIntToInt, APl2:125 

FxMulIntToIntSC, API2:125 

FxMulSC,APl2:124 

FxNegate, API2:124 

FxRoundToInt, APl2:128 

FxRoundToIntSC, API2:128 

FxSin,APl2:126 

FxSinFx,APl2:127 

FxStrToBin,APl2:129 

FxSub,APl2:124 

FxSubSC,APl2:124 

FxTan,APl2:127 

FxTanFx,APl2:127 



GESTURE_MARGIN_NEW, APl2:219 
GESTURE_MARGIN_NEW_ONLY, APl2:219 
GESTURE_MARGIN_STYLE, APl2:2 19-220 
GetAttr, APl2:75 
GetList, API2:77 
GetListX, API2:76 
GetNodeName, APl2:75 
GetSingleAttr, API2:75 
GO_DIR_CACHE, APl2:105 
GO_DIR_ENTRY, APl2: 104 
GO_DIR_ENTRY_HEADER, APl2:104 
GO_DIR_ENTRY_TYPES, APl2:104 
GO_DIR_FINDTYPE, APl2:103 
GO_DIR_USER_ATTR, APl2:104 
GOTO_BUTTON_GET_LABEL, APIl:l 77 
GOTO_BUTTON_NEW, API 1 : 1 75 
GOTO_BUTTON_NEW_ONLY, API 1 : 1 75 
GRAB_BOX_INFO, API 1 :4 1 8-4 1 9 
GRAB_BOX_NEW, API 1 :4 1 8 
GRAB_BOX_NEW_ONLY, API 1:418 
GRAB_BOX_STYLE, API 1 :4 1 7-4 1 9 
GrabBoxIntersect, API 1:420 
GrabBoxLocToRect, API 1:420 
GrabBoxPaint, API 1:420 
GWIN_GESTURE, API 1:642, API 1:644, 

API 1:646-648, API 1:650-651 
GWIN_NEW, API 1:642 
GWIN_NEW_ONLY, API 1:642 
GWIN_STYLE, API 1 :64 1 , API 1 :643 



HASH_ENTRY, APl2:224 
HASHJNFO, API2:224 
HashAddEntry, APl2:225 
HashDeleteEntry, API2:225 
HashFindData, APl2:225 



HashFindTableEntry, APl2:225 

HashFree, APl2:226 

Hashlnit, APl2:226 

HashlnitDefaults, API2:226 

HighUl6,APll:56 

HighU8, API 1:56 

HIM_ATTR_ENGINE_AVAILABLE, APl2:538 

HIM_AVAILABILITY_NOTIFY, APl2:539 

HIM_GET_SET_ENGINE, APl2:539 

HIM_NEW, API2:538 

HS_PACKET_CHAR_HANDLER, APl2:396 

HS_PACKET_METRICS, APl2:395 

HS_PACKET_NEW, APl2:397 

HS_PACKET_SEND_PACKET, APl2:396 

HS_PACKET_STATUS, APl2:396 

HWCUSTOM_NEW, API 1:655-656 

HWCUSTOM_NEW_ONLY, API 1:655 

HWLETTER_NEW, API 1:657-658 

HWLETTER_NEW_ONLY, APIl:657 

HWX_SVC_CURRENT_CHANGED, 
API2:581 

HWX_SVC_NEW, API2:581 

HWX_SVC_NEW_ONLY, APl2:581 

ICON_CHOICE_NEW, API 1 :423 
ICON_CHOICE_NEW_ONLY, API 1:423 
ICON_CHOICE_STYLE, API 1:423 
ICON_COPY_PIXELS, API 1 :429 
ICON_NEW, APll:426 
ICON_NEW_ONLY, API 1:426 
ICON_PROVIDE_BITMAP, API 1:428 
ICON_SAMPLE_BIAS, API 1:429 
ICON_STYLE, API 1:425, API 1:427 
ICON_TABLE_NEW, API 1 :43 1 
ICON_TABLE_NEW_ONLY, API 1:431 
ICON_TABLE_STYLE, API 1:431 
ICON_TOGGLE_NEW, API 1:433-434 
ICON_TOGGLE_NEW_ONLY, API 1:433 
ICON_TOGGLE_STYLE, API 1 :433-434 
ICON_WIN_METRICS, API 1 : 1 8 1 
ICON_WIN_NEW, API 1 : 1 80 
ICON_WIN_NEW_ONLY, API 1 : 1 80 
ICON_WIN_STYLE, API 1 : 1 79, API 1 : 1 8 1 
IDataDeref, APIl:9 
IDataPtr, APIl:9 
IM_ACTIVATE, APl2:560 
IM_ADD_CARDS, APl2:560 
IM_ATTR_CURRENT, APl2:547 
IM_ATTR_DEPENDENT, APl2:548 
IM_ATTR_INUSE, APl2:548 



INDEX 



661 



IM_ATTR_MODIFIED, APl2:548 
IM_ATTR_SYSTEM, APl2:548 
IM_CURRENT_NOTIFY, APl2:558 
IM_DEACTIVATE, APl2:559 
IM_DEINSTALL, APl2:555 
IM_DEINSTALL_NOTIFY, APl2:559 
IM_DUP,API2:555 
IM_EXISTS, API2:557 
IM_FIND, API2:555 
IM_GET_ITEM_ICON, APl2:56l 
IM_GET_SET_NAME, APl2:553 
IM_GET_SIZE, API2:554 
IM_GET_STATE, APl2:554 
IM_GET_VERSION, APl2:553 
IMJNSTALL, API2:554 
IM_INSTALL_EXIST, APl2:554 
IM_INUSE_NOTIFY, APl2:558 
IM_MODIFIED_NOTIFY, APl2:558 
IM_NEW, API2:549 
IM_NEW_ONLY, APl2:549 
IM_NOTIFY, APl2:558-559 
IM_RENAME_UNINSTALLED, APl2:56l 
IM_SET_INUSE, API2:552 
IM_SET_MODIFIED, APl2:552 
IM_STYLE, API2:548, APl2:550-551 
IM_UI_DEINSTALL, APl2:557 
IM_UI_DUP, API2:557 
IM_UI_INSTALL, APl2:557 
IMModuleLoad, API2:543 
IMPORT_DOC, API2:230 
IMPORT_QUERY, API2:230 
IMProgramlnstall, APl2:543 
INBX_DOC_EXIT_BEHAVIOR, APl2:405 
INBX_DOC_GET_SERVICE, APl2:401 
INBX_DOC_IN_INBOX, APl2:401 
INBX_DOC_INPUT_DONE, APl2:406-407 
INBX_DOC_STATUS_CHANGED, APl2:408 
INBXSVC_DOCUMENT, APl2:403-405 
INBXSVC_MOVE_COPY_DOC, APl2:402 
INBXSVC_NEW, API2:400-401 
INBXSVC_NEW_ONLY, APl2:400 
INBXSVC_QUERY_STATE, APl2:406 
INI_FILE_NEW, API2:542 
INI_FILE_NEW_ONLY, APl2:54l 
INI_FILE_STYLE, APl2:54l 
INPUT_EVENT, API 1:666 
INPUT_MODAL_DATA, API 1:669 
InputEventlnsert, API 1:668 
InputFilterAdd, API 1:667 
InputFilterRemove, API 1:668 



InputGetGrab, API 1:669 
InputGetTarget, API 1:668 
InputSetGrab, API 1:669 
InputSetTarget, API 1:668 
InRange, API 1:56 
INSTALL_PROTOCOL, APl2:421 
InstallMILDevice, API2:584 
INTEGER_FIELD_NEW, APll:589-590 
INTEGER_FIELD_NEW_ONLY, API 1 : 5 89 
INTEGER_FIELD_STYLE, API 1:589-590 
InvalidUUID, APl2:83 
IOBX_DOC_EXIT_BEHAVIOR, APl2:4l6 
IOBX_DOC_GET_SERVICE, APl2:4l 1 
IOBX_DOC_IN_IOBOX, APl2:4l2 
IOBX_DOC_OUTPUT_DONE, APl2:4l6, 

API2:418 
IOBX_DOC_STATUS_CHANGED, APl2:4li 
IOBXSVC_ATTR_DOC_STATE, APl2:4lO 
IOBXSVC_DOCUMENT, APl2:4l3-4l5 
IOBXSVC_MOVE_COPY_DOC, 

API2:412-413 
IOBXSVC_NEW, APl2:4l 1 
IOBXSVC_NEW_ONLY, APl2:4l 1 
IOBXSVC_QUERY_STATE, APl2:4l7 
IOBXSVC_SECTION_METRICS, APl2:4l 1 
IP_NEW, API 1:677-678 
IP_NEW_ONLY, API 1:677 
IP_STRING, API 1:684 
IP_STYLE, APIl:676, API 1:679 
IP_XLATE, API 1:677 
IP_XLATE_DATA, API 1:683 
lULMETRICS, API2:565 
IUI_SELECT_ITEM, APl2:564 
IUI_SHOW_CARD, APl2:564 

KEY_DATA, API 1:691 
KEY_MULTI, API 1:691 
KEYBOARD_NEW, API 1:694 
KEYBOARD_NEW_ONLY, API 1:694 
KEYBOARD_RET, API 1 : 694 
KEYCAP_GET_DC, API 1:699 
KEYCAP_HILITE, API 1:699 
KEYCAPJNFO, APIl:698-699 
KEYCAP_NEW, API 1:698 
KEYCAP_NEW_ONLY, API 1:698 
KEYCAP_SCAN, API 1:698 
KEYCAP_TABLE, API 1:697 
Keyin, API2:149 
KeyPressed, API2:149 
KEYSTATE, API 1:701 



KEYSTATE_CODES, API 1:702 
KEYSTATE_SCANS, API 1:702 
KeyStateConvert, API 1:702 
KeyStateDisplay, API 1:702 
KeyStateFindScan, API 1:702 
KeyStateProcess, API 1:701 
KeyStateReturn, API 1:702 
KeyStateSetup, API 1:701 

LABEL_ALIGN, API 1:446 
LABEL_BOX_METRICS, API 1:445 
LABEL_NEW, API 1:440 
LABEL_NEW_ONLY, API 1:439 
LABEL_RECT, API 1:446 
LABEL_RESOLVE, API 1:446 
LABEL_STYLE, API 1:439-441 
LDirldGetParent, APl2:l 12 
LINK_ATTRIBUTES, APl2:420 
LINK_HEADER, APl2:420 
LINK_OPERATING_STATUS, API2:420 
LINK_SERVICES, APl2:420 
LINK_STATUS, APl2:420 
LINK_TRANSMIT, APl2:421 
LIST_BOX_DATA_FREE_MODE, API 1:452 
LIST_BOX_ENTRY, API 1:452, 

API 1:454-459 
LIST_BOX_ENTRY_ENUM, API 1:452, 

APll:456 
LIST_BOX_ENTRY_STATE, API 1:452 
LIST_BOX_METRICS, API 1:452-453 
LIST_BOX_NEW, API 1:4 5 3 
LIST_BOX_POSITION_XY, API 1:452, 

API 1:457 
LIST_BOX_STYLE, API 1:451 
LIST_ENTRY, APl2:233, APl2:235-237 
LIST_ENUM, API2:237 
LIST_FILE_MODE, APl2:234 
LIST_FREE, API2:235 
LIST_FREE_MODE, API2:235 
LIST_NEW, API2:234 
LIST_NEW_ONLY, APl2:234 
LIST_NOTIFY, APl2:233, APl2:238-239 
LIST_NOTIFY_ADDITION, APl2:239 
LIST_NOTIFY_DELETION, APl2:239 
LIST_NOTIFY_EMPTY, APl2:240 
LIST_NOTIFY_REPLACEMENT, APl2:240 
LIST_STYLE, APl2:234 
LOCATION_NAME, APl2:387 
LowUl6, APIl:56 
LowU8, API 1:56 



662 



INDEX 



LVNativeName, APl2: 1 12 

LVNClose,APl2:108 

LVNCreate,APl2:108 

LVNDelete,APl2:108 

LVNDirPosDeleteAdjust, APl2:109 

LVNFlush,APl2:112 

LVNGet,APl2:106 

LVNGetAndOpenByDirld, API2:107 

LVNGetAndOpenParent, APl2:107 

LVNGetAttrlnfo, APl2:l 10 

LVNGetDirId,APl2:109 

LVNGetNumAttrs, APl2:l 10 

LVNGetSize,APl2:lll 

LVNMove,APl2:108 

LVNName,APl2:109 

LVNOpen,APl2:107 

LVNRead,APl2:lll 

LVNReadDir,APl2:109 

LVNReIease,APl2:107 

LVNSetAttrlnfo, APl2:l 10 

LVNSetSize,APl2:112 

LVNWrite,APl2:lll 

LVSetVolName, APl2: 1 06 

LVSpecificMsg, APl2:106 

LVStatus,APl2:105 

LVUpdatelnfo, APl2:106 

MakeDialEnvQHelpResId, API2:381 
MakeDialogTag, API 1:550 
MakeDynResId, API2:493 
MakeDynUUID, API2:84 
MakeGlobalWKN, API 1:57 
MakelndexedResId, APl2:493 
MakelnvalidUUID, APl2:83 
MakeListResId, API2:493 
MakeMsg, APll:9 
MakeNilUUID, APl2:83 
MakePrivateResAgent, API2:493 
MakePrivateWKN, API 1:57 
MakeProcessGlobalWKN, API 1:57 
MakeStatus, API 1:59 
MakeTag, API 1:58 
MakeTagWithFlags, API 1:58 
MakeU16,APIl:56 
MakeU32, API 1:56 
MakeWarning, API 1 :59 
MakeWKN, API 1:57 
MakeWknObjResId, APl2:493 
MakeWknResId, APl2:493 
MakeWknUUID, API2:83 



MARK_COMPARE_TOKENS, API 1 : 1 93 

MARK_COMPONENT, API 1 : 1 86, 
APIl:191,APIl:194 

MARK_GET_CHILD, API 1 : 1 96 
MARK_GOTO, API 1 : 1 92 
MARK_MESSAGE, API 1 : 1 87-1 90, 
APll:196-198 

MARK_MSG_HEADER, API 1 : 1 87 
MARK_NEW, API 1 : 1 8 8 
MARK_NEW_ONLY, API 1 : 1 8 8 
MARK_POSITION_CHILD, APIl:195 
MARK_POSITION_EDGE, API 1 : 1 95 
MARK_POSITION_GESTURE, API 1 : 1 96 
MARK_POSITION_SELECTION, APll:196 
MARK_POSITION_TOKEN, API 1 : 1 95 
MARK_SEND, API 1:190 
MARK_SHOW_TARGET, API 1 : 1 97 
MARK_TOKEN, API 1:1 86, API 1:192-193, 
APll:198 

MarkHandlerForClass, API 1 : 1 87 
MAT, API 1:234 
MatCreate, API 1:236 
MatDump, API 1:239 
Matldentity, API 1:236 
Matlnvert, API 1:237 
MatMultiply, API 1:237 
MatRotate, API 1:237 
MatScale, API 1:237 
MatTransformRECT32, API 1:239 
MatTranslate, API 1 :237 
MatWHTransforml6, API 1:238 
MatWHTransform32, API 1 :238 
MatXYTransforml6, API 1:238 
MatXYTransform32, API 1:238 
Max, API 1:56 

MENU_BUTTON_NEW, API 1:464 
MENU_BUTTON_NEW_ONLY, API 1:464 
MENU_BUTTON_PROVIDE_MENU, 

API 1:463, API 1:468-469 
MENU_BUTTON_SHOW_MENU, API 1:467 
MENU_BUTTON_STYLE, API 1:463, 

API 1:465 
MENU_NEW, API 1:475-476 
MENU_NEW_ONLY, API 1:475 
MENU_STYLE, API 1:475, API 1:477 
MIL_SVC_ADD_TO_CONFLICT_MANAGER, 

API2:587 
MIL_SVC_ARE_YOU_CONNECTED, 

API2:587 
MIL_SVC_DEVICE, APl2:584, APl2:586 
MIL_SVC_NEW, API2:585 
MIL_SVC_NEW_ONLY, APl2:584 



Min, API 1:56 

MODAL_FILTER_METRICS, API 1:482 
MODAL_FILTER_NEW, API 1:482 
MODEM_ACTIVITY, APl2:424 
MODEM_ANSWER_MODE, APl2:429 
MODEM_AUTO_ANSWER, APl2:429 
MODEM_CHARACTERISTICS, APl2:434 
MODEM_CONNECTION, APl2:427 
MODEM_CONNECTION_INFO, APl2:427 
MODEM^DCE_CONTROL, APl2:434 
MODEM_DIAL, APl2:429 
MODEM_DIAL_MODE, APl2:428 
MODEM_DUPLEX_MODE, APl2:431 
MODEM_HARDWARE_BUFFERS, APl2:434 

MODEM_HARDWARE_FEATURES, 

API2:433 
MODEM_HARDWARE_MANUFACTURER, 

API2:433 
MODEM_HARDWARE_MODEL, APl2:433 
MODEM_LINK_CONTROL, APl2:427 
MODEM.METRICS, API2:433 
MODEM_MNP_BREAK_TYPE, APl2:432 
MODEM_MNP_COMPRESSION, APl2:432 

MODEM_MNP_FLOW_CONTROL, 
API2:432 

MODEM_MNP_MODE, APl2:432 
MODEM_NEW, APl2:434 
MODEM_RESPONSE, APl2:424 
MODEM_RESPONSE_BEHAVIOR, APl2:426 
MODEM_RESPONSE_INFO, APl2:425 
MODEM_RESPONSE_MODE, API2:426 
MODEM_SEND_COMMAND, APl2:427 
MODEM_SET_AUTO_ANSWER, APl2:429 
MODEM_SIGNALLING_MODES, APl2:430 
MODEM_SIGNALLING_VOICEBAND, 
API2:430 

MODEM_SIGNALLING_WIDEBAND, 
API2:430 

MODEM_SPEAKER_CONTROL, APl2:431 
MODEM_SPEAKER_VOLUME, APl2:431 
MODEM_TIMEOUT, APl2:426 
MODEM_TONE_DETECTION, APl2:430 
MOVE_COPYJCON_DONE, API 1:473 
MOVE_COPY_ICON_NEW, API 1:472 
MOVE_COPYJCON_NEW_ONLY, API 1:471 
MOVE_COPYJCON_STYLE, API 1 :47 1 -473 
MOVEJTEMS, API2:254 
MSG_HANDLER_FLAGS, API 1:36 
MSGJNFO, API 1:36 
MSG_NOT_UNDERSTOOD, API 1:25 
msgABMgrActivate, APl2:347 



INDEX 



663 



msgABMgrChanged, APl2:348 
msgABMgrClose, APl2:347 
msgABMgrDeactivate, API2:348 
msgABMgrlsActive, API2:348 
msgABMgrList, API2:347 
msgABMgrOpen, APl2:346 
msgABMgrRegister, API2:346 
msgABMgrUnregister, API2:346 
msgAdded, API 1:25 
msgAdded, API 1:781 
msgAddObserver, API 1:23 
msgAddObserverAt, API 1:23 
msgAddrBookAdd, API2:357 
msgAddrBookAddAttr, APl2:36l 
msgAddrBookCount, APl2:362 
msgAddrBookDelete, APl2:358 
msgAddrBookEntryChanged, API2:362 
msgAddrBookEnumGroupMembers, 
API2:360 

msgAddrBookGet, APl2:355 
msgAddrBookGetJMetrics, API2:361 
msgAddrBookCetServiceDesc, APl2:360 
msgAddrBooklsAMemberOf, API2:361 
msgAddrBookSearch, APl2:358 
msgAddrBookSet, APl2:356 
msgAIMGetMaskClass, APl2:5l4 
msgAIMSetMaskClass, API2:514 
msgAMGetlnstallDir, API 1 : 1 3 1 
msgAMGetMetrics, APIl:130 
msgAMLoadAuxNotebooks, APIl:133 
msgAMLoadFormatConverters, API 1:133 
msgAMLoadHelp, APIl:132 
msgAMLoadlnitDU, API 1 : 1 3 1 
msgAMLoadMisc, API 1 : 1 3 1 
msgAMLoadOptionalDUs, APIl:133 
msgAMLoadStationery, API 1 : 1 3 1 
msgAMPopupOptions, APIl:132 
msgAMRemoveHelp, API 1 : 1 32 
msgAMRemoveStationery, APIl:132 
msgAMTerminate, APIl:134 
msgAMTerminateOK, APIl:134 
msgAMTerminateVetoed, API 1 : 1 35 
msgAMUnloadFormatConverters, 

APIl:133 
msgAMUnloadOptionalDlls, APIl:134 
msgAncestor, API 1:18 
msgAncestorlsA, APIl:18 
msgAniimSPaperDone, APIl:635 
msgAnimSPaperGetDelay, API 1:634 
msgAnimSPaperGetlnterstroke, API 1 :634 
msgAnimSPaperGetLine, API 1:634 



msgAnimSPaperGetScale, APIl:635 

msgAnimSPaperReadScribble, API 1:633 

msgAnimSPaperSetDelay, API 1:634 

msgAnimSPaperSetlnterstroke, API 1 :634 

msgAnimSPaperSetLine, API 1:634 

msgAnimSPaperSetScale, API 1:635 

msgAnimSPaperWriteScribble, API 1 :634 

msgANMAddToStationeryMenu, 
API2:522 

msgANMCopylnDoc, API2:520 

msgANMCreateDoc, APl2: 5 1 9 

msgANMCreateSect, API2:519 

msgANMDelete, API2:521 

msgANMDeleteAll, APl2:521 

msgANMGetNotebookPath, APl2:521 

msgANMGetNotebookUUID, API2:521 

msgANMGetStationeryMenu, APl2:522 

msgANMMovelnDoc, APl2:520 

msgANMOpenNotebook, APl2:522 

msgANMPopUpStationeryMenu, 
API2:522 

msgANMRemoveFromStationeryMenu, 

API2:523 
msgANMStationeryMenuNameChanged, 

API2:523 
msgAppAbout, APIl:102 
msgAppActivate, API 1:84 
msgAppActivateChild, API 1:89 
msgAppActivateChildren, API 1:89 
msgAppActivateCorkMarginChildren, 

APIl:89 
msgAppAddCards, API 1:96 
msgAppAddFloatingWin, API 1:90 
msgAppApplyEmbeddeeProps, API 1:97 
msgAppChanged, API 1:108 
msgAppChildChanged, API 1 : 1 06 
msgAppClose, API 1:87, APIl:130 
msgAppCloseChild, API 1:92 
msgAppCloseChildren, API 1:92 
msgAppClosed, APIl:105 
msgAppCloseTo, API 1:94 
msgAppCopied, API 1 : 1 07 
msgAppCopySel, APIl:102 
msgAppCreateClientWin, APIl:100 
msgAppCreated, API 1:106 
msgAppCreateLink, API 1:99 
msgAppCreateMenuBar, API 1:100 
msgAppDelnstalled, API 1 : 1 08 
msgAppDelete, APIl:89 
msgAppDeleted, API 1 : 1 06 
msgAppDeleteLink, APIl:100 



msgAppDeleteSel, API 1 : 1 03 
msgAppDirGetAttrs, APIl:l 13 
msgAppDirGetBookmark, API 1:116 
msgAppDirGetClass, APIl:l 14 
msgAppDirGetDirectNumChildren, 

API1:117 
msgAppDirGetFlags, APIl:l 13 
msgAppDirGetGlobalSequence, APIl:l 16 
msgAppDirGetNext, API 1 : 1 1 7 
msgAppDirGetNextlnit, API 1 : 1 1 6 
msgAppDirGetNumChildren, API 1 : 1 1 5 
msgAppDirGetSequence, API 1:115 
msgAppDirGetTotalNumChildren, 

API1:118 

msgAppDirGetUID, APIl: 1 14 
msgAppDirGetUUID, APIl :1 14 
msgAppDirReset, APIl : 117 
msgAppDirSeqToName, APIl: 117 
msgAppDirSetAttrs, API 1:113 
msgAppDirSetBookmark, API 1:116 
msgAppDirSetClass, APIl :1 14 
msgAppDirSetFlags, APIl :1 13 
msgAppDirSetNumChildren, API 1 : 1 1 5 
msgAppDirSetSequence, API 1:115 
msgAppDirSetUID, API 1 : 1 1 5 
msgAppDirSetUUID, APIl:ll4 
msgAppDispatch, APIl:88 
msgAppExecute, API 1:104, APl2:458 
msgAppExecuteGesture, APIl: 104 
msgAppExport, API 1:101 
msgAppFindFloatingWin, APIl:90 
msgAppFloated, APIl: 106 
msgAppGetAppWin, API 1:93 
msgAppGetBorderMetrics, API 1:97 
msgAppGetDocOptionSheetClient, 
API 1:96 

msgAppGetEmbeddedWin, API 1:93 
msgAppGetEmbeddor, API 1:93 
msgAppGetLink, API 1:100 
msgAppGetMetrics, API 1:87 
msgAppGetName, API 1:88 
msgAppGetOptionSheet, API 1:95 
msgAppGetRoot, API 1:90 
msgAppHelp, API 1 : 1 02 
msgAppHide, API 1:95 
msgAppImport, APIl: 101 
msgAppInit, API 1:8 5, API 1:129 
msgAppInstalled, API 1:108 
msgAppInvokeManager, APIl: 104 
msgAppIsPageLevel, APIl:99 
msgAppMgrActivate, API 1:123 



664 



INDEX 



msgAppMgrCopy, API 1:123 

msgAppMgrCreate, API 1 : 1 22 

msgAppMgrDelete, API 1 : 1 24 

msgAppMgrDumpSubtree, API 1:126 

msgAppMgrFSCopy, API 1:124 

msgAppMgrFSMove, API 1 : 1 24 

msgAppMgrGetMetrics, API 1 : 122, 
API2:560 

msgAppMgrGetResList, API 1:126 
msgAppMgrGetRoot, API 1 : 1 25 
msgAppMgrMove, API 1 : 1 23 
msgAppMgrRename, API 1:125 
msgAppMgrRenumber, APIl:126 
msgAppMgrRevert, API 1 : 1 26 
msgAppMgrSetlconBitmap, API 1:125 
msgAppMgrSetSmalllconBitmap, 

APIl:125 
msgAppMgrShutdown, APIl:125 
msgAppMoved, API 1 : 1 07 
msgAppMoveSel, API 1 : 1 02 
msgAppOpen, API 1 :86, API 1 : 1 29 
msgAppOpenChild, API 1:92 
msgAppOpenChildren, API 1:92 
msgAppOpened, API 1:105 
msgAppOpenTo, API 1 :94 
msgAppOwnsSelection, API 1:94 
msgAppPrint, API 1 : 1 1 
msgAppPrintSetup, API 1 : 1 1 
msgAppProvideMainWin, API 1:99 
msgAppRemoveFloatingWin, API 1:90 
msgAppRename, API 1 : 8 8 
msgAppRestore, API 1 : 8 5 , API 1 : 1 29 
msgAppRestoreFrom, API 1:85 
msgAppRevert, API 1:99 
msgAppSave, API 1:85 
msgAppSaveChild, API 1:86 
msgAppSaveChildren, API 1:86 
msgAppSaveTo, API 1:86 
msgAppSearch, API 1:103 
msgAppSelChanged, APIl:105 
msgAppSelectAll, API 1 : 1 03 
msgAppSelectAll, APl2:248 
msgAppSelOptions, APIl:103 
msgAppSend, API 1 : 1 1 
msgAppSetBorderStyle, API 1:98 
msgAppSetChildAppParentWin, APIl :87 
msgAppSetControls, API 1:97 
msgAppSetCopyable, API 1:91 
msgAppSetCorkMargin, API 1:98 
msgAppSetDeletable, API 1:91 
msgAppSetFloatingRect, API 1:95 



msgAppSetHotMode, API 1:91 
msgAppSetMainWin, API 1:87 
msgAppSetMenuLine, APIl :98 
msgAppSetMovable, API 1 :9 1 
msgAppSetName, API 1:88 
msgAppSetOpenRect, APIl:95 
msgAppSetParent, APIl -.90 
msgAppSetPrintControls, API 1:97 
msgAppSetReadOnly, API 1:91 
msgAppSetSaveOnTerminate, API 1:105 
msgAppSetScroUBars, API 1:98 
msgAppSetTitleLine, API 1:98 
msgAppShowOptionSheet, API 1:96 
msgAppSpell, API 1 : 1 04 
msgAppTerminate, API 1:91 
msgAppTerminateConditionChanged, 

APIl: 105 
msgAppTerminateOK, API 1:93 
msgAppUndo, API 1 : 1 02 
msgAppWinClose, API 1 : 146 
msgAppWinCreatelcon, API 1 : 147 
msgAppWinDelete, API 1:147 
msgAppWinDestroylcon, API 1:147 
msgAppWinEditName, APIl: 147 
msgAppWinCetMetrics, APIl: 145 
msgAppWinCetState, API 1 : 1 45 
msgAppWinCetStyie, API 1 : 1 45 
msgAppWinOpen, API 1:146 
msgAppWinSetlconBitmap, API 1:146 
msgAppWinSetLabel, API 1 : 1 46 

msgAppWinSetSmalllconBitmap, 
API 1:146 

msgAppWinSetState, API 1 : 1 45 
msgAppWinSetStyle, API 1 : 146 
msgAppWinSetUUID, API 1:147 
msgAppWinStyleChanged, API 1 : 1 47 
msgATPRespPktSize, API2:367 
msgBatteryCritical, APl2:640 
msgBatteryGetMetrics, APl2:639 
msgBatteryLow, APl2:640 
msgBatterySetLevel, API2:640 
insgBitmapCachelmageDefaults, 

API 1:227 
msgBitmapChange, API 1:228 
msgBitmapFill, API 1:227 
msgBitmapGetMetrics, API 1 :226 
msgBitmapInvert, API 1:227 
msgBitmapLighten, API 1:227 
msgBitmapMaskChange, API 1:228 
msgBitmapPixChange, API 1:227 
msgBitmapSetMetrics, API 1:226 



msgBitmapSetSize, API 1:227 
msgBoobhelfGetMetrics, API2:183 
msgBookshelfSetMetrics, APl2:184 
msgBorderConvertUnits, API 1:336 
msgBorderFlash, API 1:340 

msgBorderGetBackgroundRGB, 

API 1:336 
msgBorderGetBorderRect, API 1:337 
msgBorderGetDirty, API 1:335, API 1:382 
msgBorderGetForegroundRGB, 

API 1:336, API 1:353 
msgBorderGetlnnerRect, API 1:338 
msgBorderGetLook, API 1:334 
msgBorderGetMarginRect, API 1:338 
msgBorderGetOuterOffsets, API 1 :339 
msgBorderGetOuterSize, API 1:338 
msgBorderGetOuterSizes, API 1:339 
msgBorderGetPreview, API 1:335 
msgBorderGetSelected, API 1:335 
msgBorderGetStyle, API 1:332 
msgBorderlnkToRGB, API 1:336 
msgBorderlnsetToBorderRect, API 1:338 
msgBorderlnsetToInnerRect, API 1 :338 
msgBorderlnsetToMarginRect, API 1 :338 
msgBorderPaint, API 1:339 
msgBorderPaintForeground, API 1 :340, 

API 1:448 
msgBorderPropagate Visuals, API 1 :335 
msgBorderProvideBackground, API 1 :340 
msgBorderProvideDeltaWin, API 1 :339 
msgBorderRGBToInk, API 1:336 
msgBorderSetDirty, API 1:335, API 1:382 
msgBorderSetLook, API 1:334 
msgBorderSetPreview, API 1:334 
msgBorderSetSelected, API 1:33 5 
msgBorderSetStyle, API 1:332 
msgBorderSetStyleNoDirty, API 1:333 
msgBorderSetVisuals, API 1:337 
msgBorderTop, API 1:340 
msgBorderXOR, API 1:339 
msgBrowserBookmark, APl2: 1 96 
msgBrowserByDate, APl2:188 
msgBrowserByName, APl2:188 
msgBrowserByPage, APl2:189 
msgBrowserBySize, API2: 1 88 
msgBrowserByType, APl2: 188 
msgBrowserCollapse, APl2: 188 
msgBrowserConfirmDelete, APl2:189 
msgBrowserCreateDir, API2:187 
msgBrowserCreateDoc, APl2:196 
msgBrowserDelete, API2:189 



INDEX 



665 



msgBrowserExpand, APl2:188 

msgBrowserExport, API2: 1 89 

msgBrowserGesture, APl2:197 

msgBrowserGetBaseFlatLocator, APl2: 195 

msgBrowserGetBrowWin, API2:197 

msgBrowserCetClient, API2:195 

msgBrowserGetMetrics, APl2:190 

msgBrowserCoto, APl2:194 

msgBrowserGotoBringto, APl2: 1 94 

msgBrowserReadState, API2:190 

msgBrowserRefresh, API2: 1 89 

msgBrowserRename, APl2:189 

msgBrowserSelection, APl2:195 

msgBrowserSelectionDir, APl2:196 

msgBrowserSelectionName, APl2: 196 

msgBrowserSelectionOff, APl2:196 

msgBrowserSelectionOn, APl2:196 

msgBrowserSelectionPath, API2:195 

msgBrowserSelectionUUID, APl2: 1 95 

msgBrowserSetClient, APl2:195 

msgBrowserSetMetrics, API2:191 

msgBrowserSetSaveFile, APl2:190 

msgBrowserSetSelection, APl2:194 

msgBrowserShowBookmark, APl2:194 

msgBrowserShowButton, APl2:193 

msgBrowserShowDate, API2:193 

msgBrowserShowHeader, APl2:194 

msgBrowserShowIcon, API2:193 

msgBrowserShowSize, APl2:193 

msgBrowserShowType, APl2:193 

msgBrowserUndo, APl2:194 

msgBrowserUserColumnCetState, 
API2:192 

msgBrowserUserColumnQueryState, 

API2:193 
msgBrowserUserColumnSetState, 

API2:192 

msgBrowserUserColumnStateChanged, 
API2:192 

msgBrowserWriteState, APl2:190 
msgBusyDisplay, APIl:345 
msgBusyCetSize, API 1:346 
msgBusylnhibit, API 1:346 
msgBusySetDefaultXY, API 1:346 
msgBusySetXY, API 1:346 
msgButtonAcceptPreview, APIl:352 
msgButtonBeginPreview, API 1:352 
msgButtonButtonShowFeedback, 

API1:351 
msgButtonCancelPreview, API 1:352 
msgButtonDone, API 1:352 



msgButtonCetData, API 1:351 
msgButtonGetMetrics, API 1:350 
msgButtonGetMsg, API 1:351 
msgButtonGetStyle, API 1:350 
msgButtonNotify, API 1:353 
msgButtonNotifyManager, APIl:353 
msgButtonRepeatPreview, API 1:352 
msgButtonSetData, API 1:351 
msgButtonSetMetrics, API 1:350 
msgButtonSetMsg, API 1:351 
msgButtonSetNoNotify, APIl:351 
msgButtonSetStyle, API 1:350 
msgButtonShowFeedback, API 1:43 5 
msgButtonUpdatePreview, API 1:352 
msgByteBufChanged, APl2:206 
msgByteBufGetBuf, API2:206 
msgByteBufSetBuf, APl2:206 
msgCan, API 1:17 
msgCGGetOwner, APl2:589 
msgCGInformDisconnected, APl2:590 
msgCGOwnerChanged, API2:591 
msgCGPoliConnected, APl2:590 
msgCGSetOwner, APl2:590 
msgChanged, API 1:25 
msgChoiceGetStyle, API 1:360 

msgChoiceMgrGetOnButton, API 1:358, 
API 1:541 

msgChoiceMgrSetNoNotify, API 1:358 

msgChoiceMgrSetOnButton, API 1:358, 
API 1:542 

msgChoiceSetNoNotify, API 1:361 
msgChoiceSetStyle, API 1:360 
msgCIMFindClass, APl2:526 
msgCIMFindProgram, APl2:527 
msgCIMGetClass, APl2:526 
msgCIMGetClassList, APl2:526 
msgCIMGetTerminateStatus, APl2:528 
msgCIMLoad, APl2:527 
msgCIMTerminate, API2:527 
msgCIMTerminateOK, API2:527 
msgCIMTerminate Vetoed, API2:527 
msgClass, APIl:18 
msgCloseBoxGetStyle, API 1:372 
msgCloseBoxSetStyle, API 1:372 
msgCommandBarGetStyle, API 1:374 
msgCommandBarSetStyle, API 1:374 
msgConnectionsAddCards, API2:375 
msgConnectionsAddSheet, APl2:375 
msgConnectionsAutoConnectChanged, 
API2:376 



msgConnectionsAutoConnectltem, 

API2:374 

msgConnectionsCompareltems, API2:372 
msgConnectionsConnectedChanged, 
API2:376 

msgConnectionsConnectltem, APl2:374 

msgConnectionsEndConversation, 
API2:376 

misgConnectionsEnumerateltems, 

API2:371 
msgConnectionsEnumerateServers , 

API2:371 
msgConnectionsEnumerateTags, 

API2:372 

msgConnectionsExpandCollapse, 

API2:373 
msgConnectionsForgetltem, API2:374 
msgConnectionsGetltemlnfo, APl2:373 

msgConnectionsGetNetworkView, 
API2:372 

msgConnectionsGetServicelnfo, API2:373 

msgConnectionsGetState, APl2:371 

msgConnectionsGetTopCard, APl2:375 

misgConnectionsIsParent, API2:376 

msgConnectionsItemChanged, APl2:377 

msgConnectionsRemiemberGhanged, 

API2:377 
msgConnectionsRemiemiberltem, 

API2:374 

msgConnectionsServiceChanged, 

API2:377 
msgConnectionsSetConnectionsApp, 

API2:373 
msgConnectionsSetSelection, APl2:375 
msgConnectionsSetState, APl2:370 
msgConnectionsStartConversation, 

API2:375 
msgConnectionsTagltem, API2:373 
msgConnectionsUnAutoConnectltem, 

API2:375 
msgConnectionsUnconnectltem, 

API2:374 

misgConnectionsUpdate, API2:373 
misgContentsButtonGoto, API 1:51 1 
msgControlAcceptPreview, APIl:354, 

API 1:380, API 1:536 
msgControlBeginPreview, API 1:354, 

APIl:380, APIl:520, APIl:536 
msgControlCancelPreview, APIl :354, 

APIl:380,APIl:537 
msgControlEnable, API 1:378, API 1:609 
msgControlGetClient, APIl:378, 

API 1:520, API 1:599 



666 



INDEX 



msgControlGetDirty, API 1:362, 

API 1:378, API 1:600, API 1:622 

msgControlGetEnable, API 1:362, 
API 1:378, API 1:622 

msgControlGetMetrics, API 1:377 

msgControlGetStyle, API 1:377 

msgControlGetValue, API 1:355, 

API 1:362, API 1:379, API 1:5 19, 

API 1:528, API 1:587, 

API 1:589-590, API 1:623 
msgControlProvideEnable, API 1 :38 1 
msgControlRepeatPreview, API 1 :354, 

API 1:380, API 1:537 
msgControlSetClient, API 1:378, 

API 1:470, API 1:520, APIl:600 

msgControlSetDirty, API 1:362, 

API 1:378, API 1:400, API 1:449, 
APll:520, APIl:587, APIl:589, 
API 1:59 1-592, API 1:600, 
API 1:623 

msgControlSetEnable, API 1:362, 
API 1:378, API 1:623 

msgControlSetMetrics, API 1:377, 
API 1:449, API 1:520 

msgControlSetStyle, API 1:377, API 1:449, 
API 1:520 

msgControlSetValue, API 1:354, 

APIl:362, APIl:379, APIl:520, 

APIl:529,APIl:587, 

APIl:589-590,APIl:623 

msgControlUpdatePreview, API 1 :354, 
API 1:380 

msgCopy, API 1:14 

msgCopyRestore, API 1:14 

msgCounterGetClient, API 1:385 

msgCounterGetLabel, API 1:386 

msgCounterGetStyle, API 1:384 

msgCounterGetTotal, API 1:385 

msgCounterGetValue, API 1:385 

msgCounterGoto, APIl:386 

msgCounterlncr, API 1:385 

msgCounterNotify, API 1:386 

msgCounterSetClient, API 1:385 

msgCounterSetStyle, API 1:384 

msgCounterSetTotal, API 1:385 

msgCounterSetValue, APIl:385 

msgCreated, API 1:11 

msgCstmLayoutGetChildSpec, API 1 :369, 

API 1:4 15, API 1:545 
msgCstmLayoutGetMetrics, API 1:367 
msgCstmLayoutGetStyle, API 1:367 
msgCstmLayoutRemoveChildSpec, 

API 1:369 
msgCstmLayoutSetChildSpec, APIl :368 



msgCstmLayoutSetMetrics, API 1 :367 
msgCstmLayoutSetStyle, API 1:368 
msgDateFieldGetStyle, API 1:586 
msgDateFieldGetValue, API 1:587 
msgDateFieldSetStyle, API 1:586 
msgDateFieldSetValue, API 1:587 
msgDcAccumulateBounds, API 1:273 
msgDcAlignPattern, API 1:267 
msgDcCachelmage, API 1:278 
msgDcClipClear, API 1:272 
msgDcClipNull, API 1:272 
msgDcClipRect, API 1:272 
msgDcCopylmage, API 1 :279 
msgDcCopyPixels, API 1:283 
msgDcDirtyAccumulation, API 1:273 
msgDcDrawArcRays, API 1:274 
msgDcDrawBezier, API 1:274 
msgDcDrawChordRays, API 1 :276 
msgDcDrawEllipse, API 1:275 
msgDcDrawImage, API 1:276 
msgDcDrawImageMask, API 1:278 
msgDcDrawPageTurn, API 1:282 
msgDcDrawPixels, API 1:283 
msgDcDrawPolygon, APIl:275 
msgDcDrawPolyline, API 1:274 
msgDcDrawRectangle, API 1:275 
msgDcDrawSectorRays, API 1:276 
msgDcDrawText, API 1:280 
msgDcDrawTextDebug, API 1:281 
msgDcDrawTextRun, API 1:281 
msgDcFillWindow, API 1:276 
msgDcGetBackgroundRGB, API 1:264 
msgDcGetBounds, API 1:273 
msgDcGetCharMetrics, API 1 :28 1 
msgDcGetFillPat, API 1:266 
msgDcGetFontMetrics, API 1:282 
msgDcGetFontWidths, API 1:282 
msgDcGetForegroundRGB, API 1:264 
msgDcGetLine, API 1:262 
msgDcGetLinePat, API 1:266 
msgDcGetMatrix, API 1:271 
msgDcGetMatrixLUC, API 1:271 
msgDcGetMode, API 1 :26 1 
msgDcGetPixel, API 1:275 
msgDcGetWindow, API 1:259 
msgDcHitTest, API 1:272 
msgDcHoldLine, API 1:263 
msgDcIdentity, API 1:269 
msgDcIdentityFont, API 1:280 
msgDcInitialize, APIl:259 
msgDcInvertCoiors, API 1:264 



msgDcLUCtoLWC_RECT32, API 1:271 
msgDcLUCtoLWC_SIZE32, API 1:270 
msgDcLUCtoLWC_XY32, API 1:270 
msgDcLWCtoLUC_RECT32, API 1:270 
msgDcLWCtoLUC_SIZE32, API 1:270 
msgDcLWCtoLUC_XY32, API 1:270 
msgDcMatchRGB, API 1:264 
msgDcMeasureText, API 1:280 
msgDcMeasureTextRun, API 1:281 
msgDcMixPattern, API 1:266 
msgDcMixRGB, API 1:265 
msgDcOpenFont, API 1:280 
msgDcPlaneMask, API 1:262 
msgDcPlaneNormal, API 1 :26 1 
msgDcPlanePen, API 1 :26 1 
msgDcPop, API 1:260 
msgDcPopFont, API 1:260 
msgDcPreloadText, API 1 :28 1 
msgDcPush, API 1:259 
msgDcPushFont, API 1:260 
msgDcRotate, API 1 :269 
msgDcScale, API 1:269 
msgDcScaleFont, API 1:280 
msgDcScaleWorld, API 1:269 
msgDcScreenShot, API 1:283 
msgDcSetBackgroundColor, API 1 :265 
msgDcSetBackgroundRGB, API 1:264 
msgDcSetFillPat, API 1:266 
msgDcSetForegroundColor, API 1 :265 
msgDcSetForegroundRGB, API 1:264 
msgDcSetLine, API 1:262 
msgDcSetLinePat, API 1:265 
msgDcSetLineThickness, API 1:262 
msgDcSetMatrixLUC, API 1:271 
msgDcSetMode, API 1:260 
msgDcSetPixel, API 1:275 
msgDcSetPreMultiply, APIl:26l 
msgDcSetRop, API 1:261 
msgDcSetWindow, API 1:258 
msgDcTranslate, API 1:269 
msgDcUnitsDevice, API 1:268 
msgDcUnitsLayout, API 1:268 
msgDcUnitsMetric, API 1:267 
msgDcUnitsMil, API 1:267 
msgDcUnitsOut, API 1:268 
msgDcUnitsPen, API 1:267 
msgDcUnitsPoints, API 1:267 
msgDcUnitsRules, API 1:268 
msgDcUnitsTwips, API 1:267 
msgDcUnitsWorld, API 1:268 
msgDestroy, API 1:11 



INDEX 



667 



msgDestroy, API2:61, APl2:3l4, 

API2:469, API2:550, API2:632 
msgDialEnvBuildDialString, API2:384 
msgDialEnvChanged, API2:382 
msgDialEnvGetCountry, APl2:383 
msgDialEnvGetEnvironment, APl2:383 
msgDialEnvGetMacroIds, API2:386 
msgDialEnvIsCountryNorthAmerican, 

API2:383 
msgDialEnvOptCardApply, APl2:387 
msgDialEnvOptCardRefresh, API2:386 
msgDisable, API 1:17 
msgDrwCtxGetWindow, API 1:284, 

API 1:323 
msgDrwCtxSetWindow, API 1:284, 

API 1:323 
msgDump, API 1:14 
msgDuplicateLock, API 1:19 
msgDVCardPopupChanged, API2:211 
msgDVCloseVolume, APl2:212 
msgDVConnectTo Volume, APl2:212 
msgDVGetBasePath, APl2:210 
msgDVGetlconPanel, APl2:210 
msgDVGetOpenVols, APl2:21 1 
msgDVGetStyle, API2:209 
msgDVOpenVolume, API2:21 1 
msgDVOptionMenuNeed, APl2:21 1 
msgDVSetlconPanel, API2:21 1 
msgDVSetOptionVolume, APl2:21 1 
msgDVSetStyle, APl2:210 
msgDynTableFindButton, API2:531 
msgDynTableGetTable, API2:530 
msgDynTableSetFilllnField, APl2:53 1 
msgDynTableSetTable, APl2:531 
msgEmbeddedWinBeginCopy, API 1:161 
msgEmbeddedWinBeginMove, API 1 : 1 6 1 
msgEmbeddedWinCopy, APIl:l63 
msgEmbeddedWinDestroy, API 1:167 
msgEmbeddedWinExtractChild, 

API1:165 
msgEmbeddedWinPorwardedGetDest, 

APIl:l64 

msgEmbeddedWinGetDest, APIl:150, 
API1:164 

msgEmbeddedWinGetMark, API 1:448 

msgEmbeddedWinGetMetrics, API 1 : 1 60 

msgEmbeddedWinGetPenOffset, 

API1:163 
msgEmbeddedWinGetPrintlnfo, 

APIl:167 
msgEmbeddedWinGetStyle, API 1:161 
msgEmbeddedWinlnsertChild, API 1 : 1 65 



msgEmbeddedWinMove, API 1 : 1 62 
msgEmbeddedWinMoveCopyOK, 

API1:163 
msgEmbeddedWinPositionChild, 

APIl:l65 
msgEmbeddedWinProvidelcon, API 1:162 
msgEmbeddedWinSetStyle, APIl:l6l 
msgEmbeddedWinSetUUID, API 1:167 
msgEmbeddedWinShowChild, 

API1:166, APIl:571 
msgEnable, API 1:17 
msgEnumObservers, API 1:24 
MsgEqual, API1:9 
msgException, API 1:15 
msgExport, API2:216, APl2:249 
msgExportGetFormats, API2:216, 

API2:249 
msgExportName, APl2:217 
msgFieldAcceptPopUp, API 1:396 
msgFieldActivatePopUp, APIl:395 
msgFieldCancelPopUp, API 1:396 
msgFieldClear, API 1:397 
msgFieldCreatePopUp, API 1:396 
msgFieldCreateTranslator, APIl :398 
msgFieldFormat, API 1:399 
msgFieldGetCursorPosition, API 1 :395 
msgFieldGetDelayScribble, APIl :397 
msgFieldGetMaxLen, API 1:394 
msgFieldGetStyle, API 1:393 
msgFieldGetXlate, API 1:394 
msgFieldKeyboardActivate, API 1 :397 
msgFieldModified, API 1:397 
msgFieldNotifylnvalid, API 1:399 
msgFieldPostValidate, API 1:399 
msgFieldPre Validate, API 1:398 
msgFieldReadOnly, APIl:397 
msgFieldSetCursorPosition, APIl:395 
msgFieldSetDelayScribble, APIl :397 
msgFieldSetMaxLen, API 1:395 
msgFieldSetStyle, API 1:393 
msgFieldSetXlate, API 1:394 
msgFieldTranslateDelayed, API 1 :396 
msgFieldValidate, API 1:398 
msgFieldValidateEdit, API 1:398 
msgFIMFindId, API2:535 
msgFIMGetId, APl2:534 
msgFIMGetInstalledIdList,APl2:535 
msgFIMGetNameFromId, APl2:535 
msgFIMSetId, APl2:535 
msgFixedFieldGetStyle, API 1:588 
msgFixedFieldSetStyle, APIl:588 



msgFontListBoxGetStyle, API 1:402 
msgFrameClose, API 1 :4 1 2 
msgFrameClosed, APIl:4l4 
msgFrameDelete, API 1:411 
msgFrameDestroyMenuBar, API 1:4 10 
msgFrameFloat, API 1:4 12 
msgFrameFloated, API 1:4 14 
msgFrameGetAltVisuals, API 1:4 10 
msgFrameGetClient, API 1:4 10 
msgFrameGetClientWin, API 1:409 
msgFrameGetMenuBar, API 1:409 
msgFrameGetMetrics, API 1:408 
msgFrameGetNormalVisuals, API 1:41 1 
msgFrameGetStyle, API 1:408 
msgFramelsZoomed, API 1:41 1 
msgFrameJMoveEnable, API 1:4 11 
msgFrameResizeEnable, APIl :4l 1 
msgFrameSelect, APIl:4l3 
msgFrameSelectOK, API 1:4 13 
msgFrameSetAltVisuals, API 1:4 10 
msgFrameSetClient, API 1:4 10 
msgFrameSetClientWin, API 1:409 
msgFrameSetMenuBar, API 1:4 10 
msgFrameSetMetrics, API 1:408 
msgFrameSetNormalVisuals, API 1:41 1 
msgFrameSetStyle, API 1:409 
msgFrameSetTitle, API 1:4 10 
msgFrameShowSelected, API 1:41 1 
msgFrameTopped, API 1:4 14 
msgFrameZoom, API 1:412 
msgFrameZoomed, API 1:4 13 
msgFrameZoomOK, API 1:4 13 
msgFree, API 1:740, APIl:764 
msgFreeing, API 1:12 
msgFreeOK, APIl:ll, API 1:84 
msgFreePending, APIl: 12, API 1:221 
msgFreeSubTask, API 1:16 
msgFSChanged, APl2:68 
msgFSConnectVol, API2:97 
msgFSCopy, API2:65 
msgFSCopyNotify, APl2:66 
msgFSDelete, APl2:67 
msgFSDisconnectVol, API2:97 
msgFSEjectMedia, APl2:67 
msgFSExclVolAccess, API2:98 
msgFSFlush, APl2:67 
msgFSForceDelete, API2:68 
msgFSGetAttr, API2:63 
msgFSGetHandleMode, API2:62 
msgFSGetlnstalledVolumes, APl2: 59 



668 



INDEX 



msgFSGetPath, APl2:62 

msgFSGetSize, APl2:72 

msgFSGetVolMetrics, APl2:6l 

msgFSInstallVol, API2:96 

msgFSMakeNative, APl2:67 

msgFSMemoiyMap, API2:73 

msgFSMemoryMapFree, API2:73 

msgFSMemoryMapGetSize, APl2:73 

msgFSMemoryJMapSetSize, APl2:73 

msgFSMove, API2:64 

msgFSMoveNotify, APl2:65 

msgFSNodeExists, APl2:62 

msgFSNull,APl2:6l 

msgFSReadDir, APl2:69 

msgFSReadDirFull, API2:70 

msgFSReadDirReset, APl2:70 

msgFSRegisterVolClass, APl2:96 

msgFSRemoveVol, APl2:97 

msgFSSame, API2:62 

msgFSSeek, API2:72 

msgFSSetAttr, API2:63 

msgFSSetHandleMode, APl2:62 

msgFSSetSize, API2:72 

msgFSSetTarget, APl2:69 

msgFSSetVolName, API2:61 

msgFSTraverse, APl2:70 

msgFSUnRegisterVolClass, APl2:98 

msgFSVoIChanged, API2:69 

msgFSVoIIsBusy, API2:98 

msgFSVolList, APl2:97 

msgFSVolSpecific, APl2:68 

msgGestureJMarginGetStyle, API2:219 

msgGestureMarginSetlnkMode, API2:220 

msgGestureMarginSetStyle, APl2:220 

msgGetObserver, API 1:25 

msgGotoButtonDeleteLink, API 1:176 

msgGotoButtonEditLabel, API 1 : 1 76 

msgGotoButtonGetLabel, API 1 : 1 77 

msgGotoButtonGetMark, API 1 : 1 76 

msgGotoButtonGotoLink, API 1:176 

msgGotoButtonLinkToSelection, 
APIl:176 

msgGotoButtonPressed, API 1 : 1 77 

msgGotoButtonRePosition, API 1 : 1 77 

msgGotoButtonResetLabel, API 1 : 177 

msgGrabBoxGetMetrics, API 1 :4 1 9 

msgGrabBoxGetStyie, API 1 :4 1 8 

msgGrabBoxSetMetrics, API 1:4 19 

msgGrabBoxSetStyle, API 1:4 19 

msgGrabBoxShow, API 1:419 

msgGWinAbort, API 1:382, API 1:646 



msgGWinBadGesture, APll:648 
msgGWinBadKey, API 1:650 
msgGWinComplete, API 1:536, API 1:645 
msgGWinForwardedGesture, API 1 :569, 
API 1:576, API 1:648 

msgGWinForwardedGesture, API 1:4 14 

msgGWinForwardedKey, API 1:650, 
API 1:686 

msgGWinForwardGesture, API 1:647 
msgGWinForwardKey, API 1:649 
msgGWinGesture, API 1:646 
msgGWinGestureDone, API 1:382, 

API 1:651 
msgGWinGetFielpId, API 1:644 
msgGWinGetStyle, APIl:643 
msgGWinGetTranslator, API 1:644 
msgGWinHelp, API 1:648 
msgGWinlsComplete, API 1:650 
msgGWinKey, API 1:649 
msgGWinSetHelpId, API 1:643 
msgGWinSetStyle, APIl:643 
msgGWinSetTranslator, API 1:644 
msgGWinStroke, API 1:645 
msgGWinTransformGesture, APIl :644 
msgGWinTransformXList, API 1:645 
msgGWinTranslator, API 1:645 
msgGWinXList, APIl:570, API 1:646 
msgGWinXList, API2:37 
MsgHandler, APIl:8 
MsgHandlerArgType, API 1 :9 
MsgHandlerPrimitive, API 1:9 
MsgHandlerRingCHelper, API 1 : 9 
MsgHandlerWithTypes, API 1:9 
msgHeap, APIl: 16 

msgHIMAvailabilityChanged, APl2:539 
msgHIMGetEngine, API2:538 
msgHIMSetEngine, APl2:539 
msgHSPacketDisable, API2:397 
msgHSPacketEnable, API2:397 
msgHSPacketFreeCharHandler, API2:396 
msgHSPacketSendPacket, API2:396 
msgHSPacketSetCharHandler, API2:396 
msgHSPacketStatus, APl2:395 
msgHWXSvcCurrentChanged, API2:581 
msglconCopyPixels, API 1:429 
msglconFreeCache, API 1 :428 
msglconGetActualPictureSize, APIl :428 
msglconGetPictureSize, API 1 :427 
msglconGetRects, API 1:428 
msglconGetStyle, API 1:427 



msglconProvideBitmap, API 1 : 1 70, 

API 1:428, API 1:435 
msglconSampleBias, API 1 :429 
msglconSetPictureSize, API 1:427 
msglconSetStyle, API 1:427 
msglconToggleGetOffTag, API 1:435 
msglconToggleGetOnTag, API 1 :434 
msglconToggleGetStyle, API 1:434 
msglconToggleSetOfFTag, APIl:435 
msglconToggleSetOnTag, APIl:435 
msglconToggleSetStyle, API 1 :434 
msglconWinGetMetrics, API 1 : 1 8 1 
msglconWinGetStyle, API 1 : 1 8 1 
msglconWinSetStyle, API 1 : 1 8 1 
msglMActivate, APl2:559 
msglMAddCards, APl2:560 
msglMCurrentChanged, API2:558 
msglMDeactivate, APl2:559 
msglMDeinstall, APl2:555, API2:621 
msglMDeinstalled, API 1:403, APl2:559 
msglMDup, API2:555 
msglMExists, APl2:556 
msglMFind, APl2:555 
msglMGetCurrent, API2:552 
msglMGetDir, API2:556 
msglMGetlnstallerName, APl2:551 
msglMGetlnstallerSingularName, 

API2:551 
msglMGetlnstallPath, APl2:556 
msglMGetltemlcon, APl2:56l 
msglMGetList, APl2:553 
msglMGetName, API2:553 
msglMGetNotify, API2:560 
msglMGetSema, APl2:555 
msglMGetSettingsMenu, APl2:56l 
msglMGetSize, APl2:554 
msglMGetState, API2:554 
msglMGetStyle, API2:550 
msglMGetVerifier, APl2:556 
msglMGetVersion, APl2:553 
msglMInstall, API2:554 
msglMInstalled, APIl:403, APl2:559 
msglMInUseChanged, APl2:558 
msglMModifiedChanged, APl2:558 
msglMNameChanged, API2:558 
msglmport, API 1:130, APl2:230, APl2:249 
msglmportQuery, APIl: 130, APl2:230, 

API2:249 
msglMRemoveHandle, APl2:560 
msglMRenameUninstalledltem, APl2:56 1 
msglMSetCurrent, API2:552 
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msglMSetlnUse, APl2:552 
msglMSetModified, APl2:552 
msglMSetName, APl2:553 
msglMSetNotify, APl2:560 
msglMSetStyle, API2:551 
msglMSetVerifier, APl2:556 
msglMUIDeinstall, APl2:557 
msglMUIDup, API2:557 
msglMUIInstall, APl2:557 
msglMVerify, APl2:556 
msglNBXDocGetService, API2:401 
msglNBXDocInlnbox, API2:401 
msglNBXDocInputCancel, APl2:408 
msglNBXDocInputDone, API2:407 
msglNBXDocInputStart, APl2:407 
msglNBXDocInputStartOK, APl2:407 
msglNBXDocStatusChanged, API2:408 
msglNBXSvcCopylnDoc, API2:402 
msglNBXSvcGetEnabled, API2:406 
msglNBXSvcGetTempDir, API2:402 
msglNBXSvcInputCancel, APl2:405 
msglNBXSvcInputCleanUp, APl2:405 
msglNBXSvcInputStart, APl2:405 
msglNBXSvcLockDocument, API2:403 
msglNBXSvcMovelnDoc, API2:402 
msglNBXSvcNextDocument, API2:403 
msgINBXSvcPollDocuments,APl2:402 
msglNBXSvcQueryState, APl2:406 
msglNBXSvcScheduleDocument, 
API2:404 

msglNBXSvcSetEnabled, APl2:406 
msglNBXSvcStateChanged, APl2:406 
msglNBXSvcSwitchlcon, APl2:401 
msglNBXSvcUnlockDocument, API2:404 
msglnit, APIl:ll 

msglnputActivityTimer, API 1:670 
msglnputEvent, API 1:341, API 1:381, 

API 1:421, API 1:473, API 1:478, 
APIl:483, APIl:535, APIl:620, 
API 1:652, API 1:666, API 1:729 
msglnputCrabPopped, API 1:667 
msglnputCrabPushed, API 1:667 
msglnputModalEnd, API 1:669 
msglnputModalStart, API 1:669 
msglnputTargetActivated, API 1 :667, 
API 1:686 

msglnputTargetDeactivated, APIl :667 
tnsglntegerFieldGetStyle, API 1:590 
msglntegerFieldSetStyle, API 1:590 
msglOBXDocGetService, APl2:4l 1 
msglOBXDocInlOBox, APl2:4l2 
msglOBXDocIOCancel, APl2:4l8 



msglOBXDocIODone, APl2:4l8 
msglOBXDocIOStart, APl2:4l7 
msglOBXDocIOStartOK, API2:417 
msglOBXDocStatusChanged, APl2:4 1 8 
msglOBXSvcCopylnDoc, APl2:4l2 
msglOBXSvcGetEnabled, APl2:4l7 
msglOBXSvcGetTempDir, APl2:4l3 
msglOBXSvcIOCancel, APl2:4l6 
msglOBXSvcIOCleanUp, APl2:4l6 
msglOBXSvcIOStart, API2:415 
msglOBXSvcLockDocument, APl2:4l 4 
msglOBXSvcMovelnDoc, APl2:4l2 
msglOBXSvcNextDocument, APl2:4l 3 
msglOBXSvcPoUDocuments, APl2:4l3 
msglOBXSvcQueryState, APl2:4l6 
msglOBXSvcScheduleDocument, 

API2:415 
msglOBXSvcSetEnabled, APl2:4l7 
msglOBXSvcStateChanged, APl2:4l6 
msglOBXSvcSwitchlcon, APl2:4l 1 
msglOBXSvcUnlockDocument, 

API2:414 

msglPCancelled, API 1:400, API 1:682 
msglPClear, API 1:682 
msglPCopied, API 1:682 
msglPDataAvailable, API 1:400, API 1:683 
msglPGetClient, API 1:680 
msglPGetStyle, API 1:679 
msglPGetTranslator, API 1:680 
msglPGetXlateData, API 1:683 
msglPGetXlateStririg, API 1:684 
msglPSetClient, API 1:681 
msglPSetString, APIl:681 
msglPSetStyle, API 1:679 
msglPSetTranslator, API 1:680 
msglPTranslate, API 1:681 
msglPTransmogrified, API 1:683 
msglsA, APIl:18 
msglUIGetMetrics, APl2:564 
msglUIGetSelectionName, API2:564 
msglUIGetSelectionUID, APl2:564 
msglUISelectltem, APl2:564 
msglUIShowCard, APl2:564 
msgKeyboardReturn, API 1:694 
msgKeyBreak, APIl:694 
msgKeyCapBreak, API 1:699 
msgKeyCapGetDc, API 1:699 
msgKeyCapHilite, API 1:699 
msgKeyCapMake, API 1:699 
msgKeyCapPaintCap, APIl:698 
msgKeyCap Redisplay, API 1:699 
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rKeyCapScan, API 1:698 
jKeyChar, API 1:695 
jKeyMake, API 1:694 
jKeyMulti, API 1:695 
;LabelAlign, API 1:446 
;LabelBindStringId, API 1:443 
jLabelGetBoxMetrics, API 1:445 
jLabelGetCols, API 1:444 
jLabelGetCustomGlyph, API 1:445 
jLabelGetPontSpec, API 1:443 
jLabelGetRects, API 1:446 
jLabelGetRows, API 1:444 
jLabelGetScale, API 1:444 
jLabelGetString, API 1:441 
;LabelGetStringId, API 1:442 
^LabelGetStyle, API 1:440 
;LabelGetUnicode, API 1:442 
;LabelGetWin, API 1:443 
jLabelProvideBoxSize, API 1:447 
;LabelProvideInsPt, API 1:446 
;LabelResolveXY, API 1:446 
jLabelSetCols, API 1:445 
;LabelSetCustomGlyph, APIl:445 
;LabelSetFontSpec, API 1:443 
;LabelSetRows, API 1 :444 
;LabelSetScale, API 1:444 
;LabelSetString, API 1:442 
;LabelSetStringId, API 1:442 
;LabelSetStyle, API 1 :44 1 
;LabelSetUnicode, API 1:442 
rLabelSetWin, API 1:443 
rLINKAddressAcquire, APl2:422 
rLINKAttributesGet, APl2:421 
;LINKBufferReturn, APl2:421 
;LINKInstallProtocol, API2:421 
;LINKRemoveProtocol, APl2:421 
rLINKStatusGet, API2:422 
rLINKTransmit, APl2:421 
rListAddltem, APl2:235 
rListAddltemiAt, APl2:235 
^ListBoxAppendEntry, APIl:454, 

APIl:559 
^ListBoxDestroyEntry, APIl:458 
^ListBoxEntryGesture, API 1:459 
^ListBoxEntrylsVisible, API 1:457 
^ListBoxEnum, API 1:456 
^ListBoxFindEntry, API 1:456 
^ListBoxGetEntry, API 1:455 
;ListBoxGetMetrics, API 1:453 
^ListBoxInsertEntry, API 1:454, 

APIl:559 
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msgListBoxMakeEntryVisible, API 1 :457 
msgListBoxProvideEntry, API 1:45 8, 
API 1:558 

msgListBoxRemoveEntry, APIl:455, 

APll:559 
msgListBoxSetEntry, APIl:455, APIl:559 
msgListBoxSetMetrics, API 1:453 
msgListBoxXYToPosition, API 1:457 
msgListCall, API2:238 
msgListEnumltems, API2:237 
msgListFindltem, APl2:237 
msgListFree, API2:235 
msgListGetHeap, API2:238 
msgListGetltem, API2:237 
msgListNotifyAddition, APl2:239 
msgListNotifyDeletion, API2:239 
msgListNotifyEmpty, API2:240 
msgListNotifyReplacement, APl2:240 
msgListNumltems, APl2:237 
msgListPost, API2:239 
msgListRemoveltem, APl2:236 
msgListRemoveltemAt, APl2:236 
msgListRemoveltems, API2:237 
msgListReplaceltem, APl2:236 
msgListSend, APl2:239 
msgMarkCompareMarks, API 1:191 
msgMarkCompareTokens, API 1:193 
msgMarkCopyMark, API 1 : 1 92 
msgMarkCreateToken, APIl:192 
msgMarkDeleteToken, API 1:193 
msgMarkDeliver, API 1 : 1 88 
msgMarkDeliverNext, APIl:190 
msgMarkDeliverPos, API 1 : 1 89 
msgMarkEnterChild, APIl:197 
msgMarkEnterLevel, API 1 : 1 98 
msgMarkEnterParent, API 1 : 1 98 
msgMarkGetChild, API 1 : 1 96 
msgMarkGetComponent, API 1:191 
jtnsgMarkGetDataAncestor, API 1 : 1 93 
msgMarkGetParent, API 1 : 1 94 
msgJMarkGetToken, API 1 : 1 98 
msgMarkGetUUIDs, API 1 : 1 94 
msgMarkGotoMark, APIl:192 
msgMarkNextChild, API 1 : 1 96 
jtnsgMarkPositionAtChild, APIl:195 
msgMarkPositionAtEdge, APIl:195 
msgMarkPositionAtGesture, API 1:196 
msgMarkPositionAtSelection, API 1:196 
msgMarkPositionAtToken, API 1:195 
msgMarkSelectTarget, API 1 : 1 97 
msgMarkSend, API 1 : 1 90 



msgMarkSetComponent, APIl:191 

msgMarkShowTarget, APIl:197 

msgMarkValidateComponent, API 1 : 1 94 

msgMenuAdjustSecrions, API 1:478 

msgJMenuButtonExtractMenu, API 1 -AG] 

msgMenuButtonGetMenu, API 1:466 

msgMenuButtonGetStyle, API 1:465 

msgMenuButtonlnsertMenu, API 1 'Add 

msgMenuButtonMenuDone, API 1:469 

msgMenuButtonPlaceMenu, APIl :468, 
API1:521 

msgMenuButtonProvideMenu, API 1 :468 

msgMenuButtonProvide Width, 

API 1:466, API 1:520 
msgMenuButtonSetMenu, API 1:466 
msgMenuButtonSetStyle, API 1:465 
msgMenuButtonShowMenu, API 1:467 
msgMenuDone, API 1:477 
msgMenuGetStyle, API 1:477 
msgMenuSetStyle, API 1:477 
msgMenuShow, API 1:477 
msgMILSvcAddToConflictManager, 

API2:587 

msgMILSvcAreYouConnected, API2:587 

msgMILSvcConnectionStateResolved, 
API2:588 

msgMILSvcGetDevice, APl2:586 

msgMILSvcInstalledMILDevice, 
API2:586 

msgMILSvcPowerOfF, APl2:587 

msgMILSvcPowerOn, API2:587 

msgMILSvcSetDevice, APl2:586 

msgMILSvcStartConnectionProcessing, 
API2:588 

msgModalFilterActivate, API 1:483 

msgModalFilterDeactivate, API 1 :483 

msgModalFilterDismissWin, API 1 :483, 

API 1:489 
msgModalFilterGetFlags, API 1 :482 
msgModalFilterSetFlags, API 1:482 
msgModemActivity, APl2:424 
msgModemAnswer, APl2:429 
msgModemConnected, API2:425 
msgModemDial, APl2:429 
msgModemDisconnected, APl2:425 
msgModemErrorDetected, APl2:425 
msgModemGetConnectionlnfo, API2:427 
msgJModemGetResponseBehavior, 

API2:426 

msgModemHangUp, APl2:429 
msgModemOffHook, APl2:428 
msgModemOnline, APl2:428 



msgModemReset, APl2:427 

msgModemResponse, APl2:424 

msgModemRingDetected, API2:425 

msgModemSendCommand, API2:427 

jtnsgModemSetAnswerMode, APl2:429 

msgModemSetAutoAnswer, APl2:429 

msgModemSetCommandState, APl2:43 1 

msgModemSetDialType, APl2:428 

msgModemSetDuplex, APl2:431 

msgModemSetMNPBreakType, API2:432 

msgModemSetMNPCompression, 
API2:432 

msgModemSetMNPFlowControl, 
API2:432 

msgModemSetMNPMode, API2:431 

msgModemSetResponseBehavior, 
API2:426 

msgModemSetSignallingModes, APl2:430 
msgModemSetSpeakerControl, API2:43 1 
msgModemSetSpeaker Volume, API2:43 1 
msgModemSetToneDetecdon, APl2:430 
msgModemTransmissionError, API2:425 
msgMoveCopylconCancel, API 1 : 1 70, 

API 1:473 
msgMoveCopylconDone, APIl: 170, 

API 1:473 
msgMoveCopylconGetStyle, API 1:472 
msgMoveCopylconSetStyle, API 1:473 
msgMutate, API 1 :23 
msgNBPConfirm, API2:366 
msgNBPLookup, API2:366 
msgNBPRegister, API2:366 
msgNBPRemove, APl2:366 
msgNewArgsSize, API 1:19 
msgNewDefaults, API 1:736, API 1:739, 

APIl:763, APll:770, APIl:779, 

API1:785 
msgNewWithDefaults, API 1 : 1 1 
MsgNoError, APIl:9 
msgNoteCancel, API 1:488 
msgNoteDone, API 1:488 
msgNoteGetMetrics, API 1:487 
msgNotePaperAddMenus, APl2:246 
msgNotePaperAddModeCtrl, API2:246 
msgNotePaperAlign, APl2:246 
msgNotePaperCenter, API2:246 
msgNotePaperClear, APl2:247 
msgNotePaperClearSel, APl2:247 
msgNotePaperDeleteLine, APl2:247 
msgNotePaperDeselectLine, APl2:247 
msgNotePaperEdit, APl2:245 
msgNotePaperGetDcInfo, API2:243 
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msgNotePaperGetMetrics, API2:243 

msgNotePaperGetPenStyle, APl2:244 

msgNotePaperGetSelType, APl2:243 

msgNotePaperCetStyle, APl2:245 

msgNotePaperlnsertLine, APl2:247 

msgNotePaperMerge, APl2:246 

msgNotePaperScribble, API2:248 

msgNotePaperSelectLine, APl2:247 

msgNotePaperSelectRect, APl2:247 

msgNotePaperSetEditMode, API2:244 

msgNotePaperSetPaperAndPen, API2:244 

msgNotePaperSetPenStyle, API2:244 

msgNotePaperSetStyle, API2:244 

msgNotePaperSplit, API2:246 

msgNotePaperTidy, API2:245 

msgNotePaperTranslate, APl2:245 

msgNotePaperUntranslate, API2:245 

msgNoteSetMetrics, API 1:487 

msgNoteShow, API 1:487 

msgNotifyObservers, API 1:24 

msgNotUnderstood, API 1:25 

msgNPDataAddedltem, APl2:259 

msgNPDataDeleteltem, APl2:254 

msgNPDataEnumAIlItems, APl2:256 

msgNPDataEnumAllItemsReverse, 
API2:256 

msgNPDataEnumBaselineltems, 

API2:255 
msgNPDataEnumOverlappedltems, 

API2:255 
msgNPDataEnumSelectedltems, 

API2:256 

msgNPDataEnumSelectedltemsReverse, 
API2:256 

msgNPDataCetBaseline, APl2:257 

msgNPDataCetBounds, APl2:258 

msgNPDataCetCachedDCs, APl2:258 

msgNPDataGetCurrentltem, API2:257 

msgNPDataCetFontSpec, API2:258 

msgNPDataGetLineSpacing, APl2:258 

msgNPDataGetNextltem, API2:257 

msgNPDataGetSelBounds, API2:258 

msgNPDataHeightChanged, APl2:259 

msgNPDatalnsertltem, API2:254 

msgNPDatalnsertltetnFromView, 
API2:254 

msgNPDataltemChanged, API2:259 

msgNPDataltemCount, APl2:257 

msgNPDataltemEnumDone, API2:259 

msgNPDataMoveltem, API2:254 

msgNPDataMoveltems, APl2:254 

msgNPDataSelectedCount, APl2:257 



msgNPDataSendEnumSelectedltems, 
API2:256 

msgNPDataSetBaseline, API2:257 
msgNPDataSetFontSpec, API2:258 
msgNPDataSetLineSpacing, APl2:258 
msgNPItemAlignToBaseline, APl2:264 
msgNPItemCalcBaseline, API2:267 
msgNPItemCalcBounds, API2:267 
msgNPItemCanBeTranslated, API2:267 
msgNPItemCanBeUntranslated, 

API2:267 
msgNPItemDelete, APl2:262 
msgNPItemDelta, API2:263 
msgNPItemGetMetrics, APl2:263 
msgNPItemGetPenStyle, API2:262 
msgNPItemGetScribble, API2:266 
msgNPItemGetString, APl2:266 
msgNPItemGetViewRect, APl2:263 
msgNPItemGetWordSpacing,APl2:267 
msgNPItemHitRect, APl2:263 
msgNPItemHitRegion, APl2:266 
msgNPItemHold, APl2:264 
msgNPItemJoin, APl2:265 
msgNPItemMove, API2:263 
msgNPItemPaint, API2:264 
msgNPItemPaintBackground, APl2:262 
msgNPItemRelease, APl2:264 
msgNPItemScratchOut, API2:265 
msgNPItemSelect, API2:262 
msgNPItemSelected, APl2:262 
msgNPItemSetBaseline, APl2:263 
msgNPItemSetBounds, API2:264 
msgNPItemSetOrigin, APl2:265 
msgNPItemSetPenStyle, API2:264 
msgNPItemSetString, API2:266 
msgNPItemSplit, APl2:265 
msgNPItemSplitAs Words, APl2:265 
msgNPItemSplitGesture, API2:265 
msgNPItemTie, APl2:265 
msgNPItemToScribble, APl2:266 
msgNPItemToText, APl2:266 
msgNuU, APIhlO 
MsgNum, API1:9 
msgNumObservers, APIl:25 
msgObjectAncestorlsA, API 1:21 
msgObjectClass, API 1:21 
msgObjectlsA, API 1:20 
msgObjectNew, API 1:22 
msgObjectOwner, API 1:21 
msgObjectValid, API 1:21 
msgObject Version, API 1:22 



msgOBXDocGetService, APl2:44l 
msgOBXDocInOutbox, APl2:44l 
msgOBXDocOutputCancel, API2:447 
msgOBXDocOutputDone, API2:447 
msgOBXDocOutputStart, APl2:447 
msgOBXDocOutputStartOK, APl2:447 
msgOBXDocStatusChanged, API2:448 
msgOBXSvcCopylnDoc, APl2:442 
msgOBXSvcGetEnabled, APl2:446 
msgOBXSvcGetTempDir, APl2:442 
msgOBXSvcLockDocument, API2:443 
msgOBXSvcMovelnDoc, APl2:44l 
msgOBXSvcNextDocument, API2:443 
msgOBXSvcOutputCancel, APl2:445 
msgOBXSvcOutputCleanUp, API2:445 
msgOBXSvcOutputStart, API2:445 
msgOBXSvcPoUDocuments, API2:442 
msgOBXSvcQueryState, APl2:446 

msgOBXSvcScheduleDocument, 

API2:444 
msgOBXSvcSetEnabled, APl2:446 
msgOBXSvcStateChanged, APl2:446 
msgOBXSvcSwitchlcon, APl2:44l 
msgOBXSvcUnlockDocument, API2:444 
ionAddAndlnsertCard, APIl:500 
ionAddCard, API 1:498 
ionAddCards, APIl:510, API2:249 
ionAddFirstCard, API 1:499 
ionAddLastCard, API 1:499 
ionApplicable, API 1:503 
ionApplicableCard, API 1 : 508 
ionApply, API 1:503 
ionApplyAndClose, API 1:503 
ionApplyCard, API 1:507 
ionBookProvideContents, 

APIl:511 
ionCardMenuDone, API 1:505 
ionClean, API 1:504 
ionCleanCard, APIl:508 
ionClose, API 1:504 
ionClosed, APIl:510 
ionCreateSheet, API 1:5 10 
ionDirty, API 1:504 
ionDirtyCard, API 1:508 
ionEnumCards, API 1:497 
ionExtractCard, API 1:501 
ionGetCard, API 1:495 
lonGetCardAndName, API 1:49 6 
lonGetCardMenu, API 1:504 
ionGetCards, APIl:502 
lonGetNeedCards, API 1:49 5 
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msgOptionGetStyle, API 1:494 
msgOptionGetTopCard, API 1:496 
msgOptionProvideCardDirty, API 1 : 506 
msgOptionProvideCardWin, API 1:505 
msgOptionProvideTopCard, APIl :506 
msgOptionRefresh, API 1:503 
msgOptionRefreshCard, API 1:507 
msgOptionRemoveCard, API 1:500 
msgOptionRetireCard, API 1:509 
msgOptionSetCard, API 1:498 
msgOptionSetNeedCards, API 1:495 
msgOptionSetStyle, API 1:495 
msgOptionShowCard, API 1:501 
msgOptionShowCardAndSheet, API 1 :502 
msgOptionShowSheet, APIl: 505 
msgOptionShowTopCard, API 1:502 
msgOptionToggleDirty, API 1:504 
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PenPoint™ Application Programmatic Interface, Volume II 

Together with Volume I, PenPoint™ Application Programmatic Interface, Volume II 
provides a complete reference to the classes, messages, functions, and structures 
provided by the PenPoint Software Development Kit (SDK), 

The parts in the PenPoint API Reference ^xc organized in parallel with the pans in the 
PenPoint Architectural Reference (also available from Addison- Wesley). This volume 
contains datasheets on the APIs to the: 

Text subsystem 
PenPoint file system 
PenPoint operating system kernel 
Utility classes 
Connectivity classes 
PenPoint resource classes 
Installation interface 
PenPoint services 
Miscellaneous other classes 

Other volumes in the GO Technical Library are: 

PenPoint Application Writing Guide provides a tutorial on writing PenPoint 
applications, including many coding samples. 

PenPoint User Interface Design Reference describes the elements of the PenPoint 
Notebook User Interface, sets standards for using those elements, and describes how 
PenPoint uses the elements. 

PenPoint Development Tools describes the environment for developing, 
debugging, and testing PenPoint applications. 

PenPoint Architectural Reference, Volume I presents the concepts of the fundamental 
PenPoint classes. 

PenPoint Architectural Reference, Volume II presents the concepts of the supplemental 
PenPoint classes. 

PenPoint API Reference, Volume /provides a complete reference to the supplemental 
PenPoint classes, messages, and data structures. 

GO Corporation was founded in September 1987 and is a leader in pen computing 
technology for mobile professionals. The company's mission is to expand the 
accessibility and utility of computers by establishing its pen-based operating system 
as a standard. 
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